opencode-thrum-pro 0.1.5 → 0.1.6

package/assets/skills/persistent-watcher-archetype/resources/roster-watch_test.sh

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+# roster-watch_test.sh — unit tests for roster-watch.sh's
+# resolve_watch_params() (the ".thrum/redirect" fix), plus a
+# coverage bonus for thrum-watch-pane-capture.sh's PARAMS_FILE resolution
+# logic (inline harness — that script isn't structured as sourceable
+# functions the way roster-watch.sh is; see Scenario 3 below).
+#
+# Run: bash claude-plugin/skills/persistent-watcher-archetype/resources/roster-watch_test.sh
+# (or: SCRIPT_UNDER_TEST=/path/to/alt-roster-watch.sh bash roster-watch_test.sh
+#  to run Scenario 1 against a different implementation, e.g. for a manual
+#  RED-before/GREEN-after check against a deliberately-reverted copy.)
+#
+# All tests are hermetic: every fixture is a throwaway tree under mktemp -d,
+# cleaned up via a trap; nothing here touches the real repo's .thrum, a live
+# daemon, or the network.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT_UNDER_TEST="${SCRIPT_UNDER_TEST:-$SCRIPT_DIR/roster-watch.sh}"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_UNDER_TEST" || {
+  echo "roster-watch.sh not found/sourceable at $SCRIPT_UNDER_TEST -- resolve_watch_params is missing" >&2
+  exit 1
+}
+
+pass=0
+fail=0
+assert_eq() {
+  local desc="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "PASS: $desc"; pass=$((pass + 1));
+  else echo "FAIL: $desc -- expected '$expected' got '$actual'"; fail=$((fail + 1)); fi
+}
+assert_ne() {
+  local desc="$1" unexpected="$2" actual="$3"
+  if [ "$unexpected" != "$actual" ]; then echo "PASS: $desc"; pass=$((pass + 1));
+  else echo "FAIL: $desc -- '$actual' unexpectedly equals '$unexpected'"; fail=$((fail + 1)); fi
+}
+
+# roster_count <file> -- number of entries in the "roster" array of a
+# watch_params.json fixture. Uses python3 (already a hard dependency of
+# roster-watch.sh itself, e.g. load_roster()).
+roster_count() {
+  python3 -c '
+import json, sys
+try:
+    d = json.load(open(sys.argv[1]))
+    print(len(d.get("roster", [])))
+except Exception:
+    print(-1)
+' "$1" 2>/dev/null
+}
+
+# mk_watch_params <file> <n> -- write a watch_params.json fixture with a
+# roster array of n plain-string entries.
+mk_watch_params() {
+  local file="$1" n="$2"
+  mkdir -p "$(dirname "$file")"
+  python3 -c '
+import json, sys
+n = int(sys.argv[1])
+json.dump({"roster": [f"agent{i}" for i in range(n)]}, open(sys.argv[2], "w"))
+' "$n" "$file"
+}
+
+AGENT="watcher_primary"
+
+# =============================================================================
+# Scenario 1 (MANDATORY, cmain-required regression guard): a worktree that
+# redirects to a main-repo tree. The "roster-editing agent's Edit-tool write"
+# lands in the REDIRECT TARGET (main-repo) copy -- that's the physically
+# correct, shared, redirect-resolved location per internal/paths/paths.go
+# AgentDir ("the agents/ tree is shared, not per-worktree"), and it's what
+# resolve_watch_params must read. A worktree-LOCAL copy at the naive,
+# unresolved path is a decoy: it's what a broken script (SCRIPT_DIR-relative,
+# no redirect-follow) would read instead, and it must be ignored.
+#
+# Bead framing: main-repo (correct) copy has 25 entries ("not 25" in the
+# bug's own words -- i.e. the FIXED behavior must see 25); the worktree-local
+# decoy has 24 (the stale/wrong count an unfixed script would see instead).
+# =============================================================================
+echo "--- Scenario 1: regression guard (redirect-resolved read wins over worktree-local decoy) ---"
+
+worktree_root="$(mktemp -d)"
+mainrepo_root="$(mktemp -d)"
+trap 'rm -r -- "$worktree_root" "$mainrepo_root" 2>/dev/null || true' EXIT
+
+mkdir -p "$worktree_root/.thrum"
+printf '%s/.thrum' "$mainrepo_root" > "$worktree_root/.thrum/redirect"
+
+mainrepo_params="$mainrepo_root/.thrum/agents/$AGENT/watch_params.json"
+worktree_decoy_params="$worktree_root/.thrum/agents/$AGENT/watch_params.json"
+
+mk_watch_params "$mainrepo_params" 25       # the real edit, correctly-wired fixture
+mk_watch_params "$worktree_decoy_params" 24 # the stale worktree-local decoy
+
+resolved="$(resolve_watch_params "$worktree_root" "$AGENT")"
+assert_eq "resolves to the redirect-target (main-repo) path" "$mainrepo_params" "$resolved"
+assert_ne "does NOT resolve to the worktree-local decoy path" "$worktree_decoy_params" "$resolved"
+assert_eq "resolved file has the EDITED count (25, not 24)" "25" "$(roster_count "$resolved")"
+
+# --- Negative control: prove the resolver is really reading the redirect
+# target's CONTENT, not something incidental (e.g. a hardcoded/dead-end
+# path, or a test bug where both fixtures happen to satisfy the assertion
+# regardless of which tree holds what). Swap which tree holds the "right"
+# (25) vs "wrong" (24) count, WITHOUT changing which path resolve_watch_params
+# points at. If the resolver is doing real redirect-following, the resolved
+# PATH stays the main-repo path (structural, content-independent), but the
+# roster COUNT read from it must now be 24 (the swapped-in wrong count) --
+# i.e. the same "expect 25" assertion used above must now correctly FAIL,
+# proving the earlier PASS wasn't vacuous.
+echo "--- Scenario 1 (mis-wired control): swapped fixture must make the same assertion fail ---"
+mk_watch_params "$mainrepo_params" 24        # now the main-repo copy is "stale"
+mk_watch_params "$worktree_decoy_params" 25  # decoy now happens to hold the "right" count
+
+resolved_mis="$(resolve_watch_params "$worktree_root" "$AGENT")"
+assert_eq "mis-wired: resolved path is unchanged (still the main-repo path)" "$mainrepo_params" "$resolved_mis"
+got_count="$(roster_count "$resolved_mis")"
+if [ "$got_count" = "25" ]; then
+  echo "FAIL: mis-wired control -- expected count MISMATCH (resolver should read the swapped-in 24, not the decoy's 25) but got 25; this would mean the test passes regardless of fixture wiring"
+  fail=$((fail + 1))
+else
+  echo "PASS: mis-wired control -- resolver reads 24 (the main-repo tree's current content), confirming it is not incidentally reading the decoy"
+  pass=$((pass + 1))
+fi
+
+# restore correct wiring for anything downstream that might reuse these dirs
+mk_watch_params "$mainrepo_params" 25
+mk_watch_params "$worktree_decoy_params" 24
+
+rm -r -- "$worktree_root" "$mainrepo_root"
+trap - EXIT
+
+# =============================================================================
+# Scenario 2: existing (non-worktree) behavior unchanged -- no .thrum/redirect
+# file at all means this IS the main repo; resolve_watch_params must fall
+# through to the LOCAL .thrum/agents/<agent>/watch_params.json.
+# =============================================================================
+echo "--- Scenario 2: no redirect file -> resolves to local .thrum path (no regression) ---"
+
+mainrepo_only="$(mktemp -d)"
+trap 'rm -r -- "$mainrepo_only" 2>/dev/null || true' EXIT
+
+local_params="$mainrepo_only/.thrum/agents/$AGENT/watch_params.json"
+mk_watch_params "$local_params" 7
+# deliberately no redirect file created
+
+resolved_local="$(resolve_watch_params "$mainrepo_only" "$AGENT")"
+assert_eq "no-redirect case resolves to the local path" "$local_params" "$resolved_local"
+assert_eq "no-redirect case reads the local file's real content" "7" "$(roster_count "$resolved_local")"
+
+rm -r -- "$mainrepo_only"
+trap - EXIT
+
+# =============================================================================
+# Scenario 3 (bonus): thrum-watch-pane-capture.sh's PARAMS_FILE resolution.
+# That script is NOT structured as sourceable functions (its redirect logic
+# is a flat sequence of top-level assignments between REPO_ROOT and
+# FALLBACK_SCRIPT, guarded by no function boundary) -- sourcing the whole
+# file would run its lock-dir/roster-load/capture logic as a side effect.
+# So this reproduces JUST that resolution snippet as a tiny inline harness,
+# verified byte-for-byte against the live file below (so the harness can't
+# silently drift from the real script) before asserting on it.
+# =============================================================================
+echo "--- Scenario 3 (bonus): thrum-watch-pane-capture.sh PARAMS_FILE resolution (inline harness) ---"
+
+pane_capture_script="$SCRIPT_DIR/thrum-watch-pane-capture.sh"
+if [ ! -f "$pane_capture_script" ]; then
+  echo "SKIP: $pane_capture_script not found -- skipping Scenario 3"
+else
+  expected_snippet='THRUM_DIR="${REPO_ROOT}/.thrum"
+if [ -f "${THRUM_DIR}/redirect" ]; then
+  THRUM_DIR="$(tr -d '"'"'[:space:]'"'"' < "${THRUM_DIR}/redirect")"
+fi
+PARAMS_FILE="${THRUM_DIR}/agents/${AGENT_NAME}/watch_params.json"'
+  live_snippet="$(sed -n '/^THRUM_DIR="\${REPO_ROOT}\/\.thrum"$/,/^PARAMS_FILE=/p' "$pane_capture_script")"
+  if [ "$live_snippet" != "$expected_snippet" ]; then
+    echo "FAIL: Scenario 3 harness has drifted from the live PARAMS_FILE resolution snippet in $pane_capture_script -- update the harness (this is a test-maintenance guard, not a product assertion)"
+    echo "  live snippet was:"
+    echo "$live_snippet" | sed 's/^/    /'
+    fail=$((fail + 1))
+  else
+    echo "PASS: inline harness matches the live PARAMS_FILE resolution snippet verbatim"
+    pass=$((pass + 1))
+
+    resolve_pane_capture_params() {
+      # Args: repo_root, agent_name. Mirrors the verbatim snippet above.
+      local REPO_ROOT="$1" AGENT_NAME="$2" THRUM_DIR
+      THRUM_DIR="${REPO_ROOT}/.thrum"
+      if [ -f "${THRUM_DIR}/redirect" ]; then
+        THRUM_DIR="$(tr -d '[:space:]' < "${THRUM_DIR}/redirect")"
+      fi
+      printf '%s/agents/%s/watch_params.json\n' "${THRUM_DIR}" "${AGENT_NAME}"
+    }
+
+    pc_worktree="$(mktemp -d)"
+    pc_mainrepo="$(mktemp -d)"
+    trap 'rm -r -- "$pc_worktree" "$pc_mainrepo" 2>/dev/null || true' EXIT
+
+    mkdir -p "$pc_worktree/.thrum"
+    printf '%s/.thrum' "$pc_mainrepo" > "$pc_worktree/.thrum/redirect"
+    pc_mainrepo_params="$pc_mainrepo/.thrum/agents/$AGENT/watch_params.json"
+    pc_decoy_params="$pc_worktree/.thrum/agents/$AGENT/watch_params.json"
+    mk_watch_params "$pc_mainrepo_params" 25
+    mk_watch_params "$pc_decoy_params" 24
+
+    pc_resolved="$(resolve_pane_capture_params "$pc_worktree" "$AGENT")"
+    assert_eq "pane-capture: redirect present -> resolves to main-repo path" "$pc_mainrepo_params" "$pc_resolved"
+    assert_ne "pane-capture: does NOT resolve to worktree-local decoy" "$pc_decoy_params" "$pc_resolved"
+    assert_eq "pane-capture: resolved file has the edited count (25)" "25" "$(roster_count "$pc_resolved")"
+
+    rm -r -- "$pc_worktree" "$pc_mainrepo"
+    trap - EXIT
+
+    pc_mainrepo_only="$(mktemp -d)"
+    trap 'rm -r -- "$pc_mainrepo_only" 2>/dev/null || true' EXIT
+    pc_local_params="$pc_mainrepo_only/.thrum/agents/$AGENT/watch_params.json"
+    mk_watch_params "$pc_local_params" 3
+    pc_resolved_local="$(resolve_pane_capture_params "$pc_mainrepo_only" "$AGENT")"
+    assert_eq "pane-capture: no redirect -> resolves to local path" "$pc_local_params" "$pc_resolved_local"
+    rm -r -- "$pc_mainrepo_only"
+    trap - EXIT
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Scenario 4: load_roster's capture_daemon_overrides field.
+# Regression guard for a REAL bug caught during that scrub: the plain-string
+# roster-entry branch of load_roster's python emitter originally printed
+# only 3 `|` separators (agent|||override) for what is now a 5-FIELD
+# schema (agent|host|tmux|runtime|override, needing 4 separators) -- the
+# missing separator silently shifted every subsequent field left by one,
+# so a string-roster-entry agent's override always read back empty even
+# when set. Covers both roster-entry shapes (plain string and the
+# {agent_id,hostname,tmux_session} dict form) so a similar off-by-one in
+# either emitter branch fails loud here instead of silently dropping an
+# agent's --daemon-id routing in production.
+# ---------------------------------------------------------------------------
+echo "--- Scenario 4: capture_daemon_overrides read into ROSTER_DAEMON_OVERRIDE ---"
+d4_dir="$(mktemp -d)"
+trap 'rm -r -- "$d4_dir" 2>/dev/null || true' EXIT
+d4_params="$d4_dir/watch_params.json"
+python3 -c '
+import json, sys
+data = {
+    "roster": [
+        "agent_plain_no_override",
+        "agent_plain_with_override",
+        {"agent_id": "agent_dict_with_override", "hostname": "boxc", "tmux_session": "sess"},
+    ],
+    "capture_daemon_overrides": {
+        "agent_plain_with_override": "d_PLAINOVERRIDE00000000000",
+        "agent_dict_with_override": "d_DICTOVERRIDE0000000000000",
+    },
+}
+json.dump(data, open(sys.argv[1], "w"))
+' "$d4_params"
+
+load_roster "$d4_params"
+
+assert_eq "capture_daemon_overrides: roster has 3 entries" "3" "${#ROSTER[@]}"
+assert_eq "capture_daemon_overrides: entry 0 agent id" "agent_plain_no_override" "${ROSTER[0]}"
+assert_eq "capture_daemon_overrides: plain string entry with NO override reads empty" "" "${ROSTER_DAEMON_OVERRIDE[0]}"
+assert_eq "capture_daemon_overrides: entry 1 agent id" "agent_plain_with_override" "${ROSTER[1]}"
+assert_eq "capture_daemon_overrides: plain string entry WITH override reads its daemon id" "d_PLAINOVERRIDE00000000000" "${ROSTER_DAEMON_OVERRIDE[1]}"
+assert_eq "capture_daemon_overrides: entry 2 agent id" "agent_dict_with_override" "${ROSTER[2]}"
+assert_eq "capture_daemon_overrides: dict-form entry's hostname still reads correctly (field alignment intact)" "boxc" "${ROSTER_HOSTNAME[2]}"
+assert_eq "capture_daemon_overrides: dict-form entry's tmux_session still reads correctly" "sess" "${ROSTER_TMUX_SESSION[2]}"
+assert_eq "capture_daemon_overrides: dict-form entry WITH override reads its daemon id" "d_DICTOVERRIDE0000000000000" "${ROSTER_DAEMON_OVERRIDE[2]}"
+
+rm -r -- "$d4_dir"
+trap - EXIT
+
+# Default/absent capture_daemon_overrides -> every entry inert (empty).
+d4b_dir="$(mktemp -d)"
+trap 'rm -r -- "$d4b_dir" 2>/dev/null || true' EXIT
+d4b_params="$d4b_dir/watch_params.json"
+python3 -c '
+import json, sys
+json.dump({"roster": ["agent_a", "agent_b"]}, open(sys.argv[1], "w"))
+' "$d4b_params"
+load_roster "$d4b_params"
+assert_eq "capture_daemon_overrides absent from watch_params.json: entry 0 inert" "" "${ROSTER_DAEMON_OVERRIDE[0]}"
+assert_eq "capture_daemon_overrides absent from watch_params.json: entry 1 inert" "" "${ROSTER_DAEMON_OVERRIDE[1]}"
+rm -r -- "$d4b_dir"
+trap - EXIT
+
+# ---------------------------------------------------------------------------
+echo "----------------------------------------"
+echo "roster-watch: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/assets/skills/persistent-watcher-archetype/resources/thrum-capture-fallback.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # thrum-capture-fallback.sh — capture/key an agent, falling back to an SSH
 # hop when the local `thrum tmux capture|key` proxy path fails with a known
-# cross-daemon proxy-routing error signature (thrum-7vwgy / thrum-zkqut
-# class bugs: same-host dual-daemon caller-identity collision, and a
+# cross-daemon proxy-routing error signature (known bug classes:
+# same-host dual-daemon caller-identity collision, and a
 # phantom-routing regression on daemon builds predating EnsureProxies).
 #
 # `thrum tmux capture <agent>` ALREADY reaches remote agents by name via the

package/assets/skills/persistent-watcher-archetype/resources/thrum-watch-pane-capture.sh

@@ -3,7 +3,7 @@
 # thrum-watch-pane-capture.sh
 #
 # The generic, roster-driven pane-watch capture-loop script that ships with
-# the persistent-watcher-archetype plugin skill (thrum-3mhrt). Works for
+# the persistent-watcher-archetype plugin skill. Works for
 # BOTH a persistent-watcher-archetype watcher and the brainstorm-steward
 # (one parameterized script serves both — the only differences, roster
 # contents and cadence, are already `watch_params.json` fields, not script
@@ -18,8 +18,8 @@
 #   capture each member's pane (local `thrum tmux capture` first, ALWAYS —
 #   `thrum tmux capture <agent>` already reaches remote agents by name via
 #   the normal rpcrouter proxy; the SSH hop below is a resilience FALLBACK
-#   for when that path is broken on the caller's side, e.g. thrum-7vwgy/
-#   thrum-zkqut-class bugs, never a fleet-wide-watching enabler in its own
+#   for when that path is broken on the caller's side, e.g. known
+#   cross-daemon proxy-routing bug classes, never a fleet-wide-watching enabler in its own
 #   right, and never SSH-first) -> run each capture through `thrum detect
 #   --category permission` -> for a STABLE (unchanged across two captures,
 #   two seconds apart) detected permission prompt, flag it in the report ->
@@ -55,7 +55,7 @@
 #
 # THRUM MONITOR EXAMPLE (see SKILL.md for the full, current recipe —
 # --notify-on-success is MANDATORY: a --schedule'd job delivers NOTHING on
-# --match alone, thrum-ruz1z/S5c):
+# --match alone):
 #   thrum monitor start --name <you>-pane-watch \
 #     --match "^watch-tick: (cycle done|RESOLUTION-FAIL)" \
 #     --to @<you> \
@@ -72,7 +72,19 @@ AGENT_NAME="$(basename -- "${SCRIPT_DIR}")"
 # -- never hardcode REPO_ROOT (the prior box-specific adaptation this
 # script generalizes did, and that was exactly the thing to fix).
 REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../../.." >/dev/null 2>&1 && pwd)"
-PARAMS_FILE="${SCRIPT_DIR}/watch_params.json"
+# Resolve watch_params.json through .thrum/redirect. The
+# agents/ tree is the SHARED, redirect-resolved (main-repo) tree, not
+# per-worktree (see internal/paths/paths.go AgentDir) -- reading it
+# straight off SCRIPT_DIR (this copy's own worktree-local location) reads
+# the wrong, stale file whenever this script is deployed into a feature
+# worktree that redirects: a roster-editing agent's Edit-tool write lands
+# in the redirect-resolved main-repo copy, and this script would silently
+# keep reading the worktree-local one and never see the edit.
+THRUM_DIR="${REPO_ROOT}/.thrum"
+if [ -f "${THRUM_DIR}/redirect" ]; then
+  THRUM_DIR="$(tr -d '[:space:]' < "${THRUM_DIR}/redirect")"
+fi
+PARAMS_FILE="${THRUM_DIR}/agents/${AGENT_NAME}/watch_params.json"
 FALLBACK_SCRIPT="${SCRIPT_DIR}/thrum-capture-fallback.sh"
 
 LOG_DIR="${REPO_ROOT}/.thrum/var/log"
@@ -139,7 +151,7 @@ fi
 # script (no mapfile/readarray, no `local -n`, no bash-4 associative
 # arrays -- parallel indexed arrays instead). Test with `/bin/bash
 # thrum-watch-pane-capture.sh`, not just `bash ...` or `./...`, or this
-# class of bug only surfaces on the live scheduled run (thrum-dnatz).
+# class of bug only surfaces on the live scheduled run.
 ROSTER=()
 while IFS= read -r line; do
   [ -n "${line}" ] && ROSTER+=("${line}")
@@ -182,7 +194,7 @@ log "roster: ${ROSTER[*]}"
 # against the current CLI, regardless of how the field/scope names read.
 is_placeholder() {
   case "$1" in
-    ""|PENDING-LEON|PENDING|TODO|TBD) return 0 ;;
+    ""|PENDING|TODO|TBD) return 0 ;;
     *) return 1 ;;
   esac
 }
@@ -267,7 +279,7 @@ resolve_roster_targets() {
 build_topology_table
 resolve_roster_targets
 
-# Fork default (coordinator-resolved, thrum-3mhrt plan): if EVERY roster
+# Fork default (coordinator-resolved plan): if EVERY roster
 # agent failed resolution, that is itself worth surfacing as a real
 # problem (likely a fleet-wide topology/agent_pool data gap), not a clean
 # tick -- flip the summary line's marker so `--match` treats it as a

package/assets/skills/prime-agent/SKILL.md

@@ -81,6 +81,16 @@ lifetime.
 If the session will exceed ~30 minutes, or coordination with other agents is
 needed, defer to `thrum prime`.
 
+**Exception: post-`/thrum:compact` resume — MANUAL FALLBACK ONLY.** After
+`/thrum:compact` or `/thrum:compact-extended`, the SessionStart hook now
+auto-injects a zero-turn light briefing (`thrum prime --light`) directly into
+context on a healthy daemon — no turn spent reading a file or running a skill.
+This skill is the correct choice here only as a **fallback**, when that
+auto-injection didn't fire or failed (e.g. the hook's "auto-injection failed"
+notice, daemon unreachable). In that fallback case: read the snapshot first,
+then run this skill. See `claude-plugin/commands/compact.md`'s "How resume
+works" section.
+
 ## After Step 2
 
 Once both steps complete, proceed with the work the wake-primer asked for.

package/assets/skills/project-setup/SKILL.md

@@ -381,16 +381,13 @@ bd dep add <later-epic-id> <earlier-epic-id>
 ### Create Tasks
 
 When creating > 6 tasks, delegate to parallel sub-agents — one per epic. Each
-sub-agent (sonnet-low is sufficient — the work is mechanical) gets the epic ID, the
+sub-agent (a cheap tier is sufficient — the work is mechanical; model per `choosing-subagent-models`) gets the epic ID, the
 list of `bd create --title=... --type=task --priority=N --description=...`
 commands to run, the within-epic `bd dep add <later_id> <earlier_id>` ordering
 commands, and instructions to return the created task IDs and titles. Invoke
 `efficient-multi-agent-research` § Core Pattern for launch-and-wait mechanics.
 
-> **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
-> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
-> operator-ask or a skill step that names it. See the
-> `choosing-subagent-models` skill for the full policy.
+> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
 
 After sub-agents return IDs, set cross-epic dependencies directly (requires IDs
 from multiple sub-agents):
@@ -478,20 +475,24 @@ template's "Logging Refactoring Opportunities" section.
 
 If not found, create one:
 
-`--description` is multi-line prose — never double-quoted inline. On
-`scripts/bd-shared`, `--stdin`/`--body-file` are refused (remote-path
-resolution + silent-empty-body hazards), so write it to a scratch file and
-pass `-d "$(cat <file>)"`; see the role preamble's 🔴 PROSE INTO A COMMAND
-rule.
+`--description` is multi-line prose — never double-quoted inline. Use
+`--body-file` to pass the content from a file instead; see the role preamble's
+🔴 PROSE INTO A COMMAND rule. `scripts/bd-shared` delivers `--body-file` (and
+`--stdin`) content: it reads the file on your box and pipes those bytes to bd,
+and an empty or blank body is refused loudly; only `-f`/`--file` and `--graph`
+(bulk-plan files) are refused there. Scratch files go in `/private/tmp` on macOS,
+where `/tmp` is a symlink (check `[ -L /tmp ]`), and in `/tmp` elsewhere.
 
 ```bash
-cat > /tmp/refactor-epic-desc.md <<'EOF'
+# Scratch dir: /private/tmp on macOS (where /tmp is a symlink), /tmp elsewhere.
+SCRATCH=$([ -L /tmp ] && echo /private/tmp || echo /tmp)
+cat > "$SCRATCH/refactor-epic-desc.md" <<'EOF'
 Persistent backlog for refactoring, DRY improvements, and code
 organization opportunities discovered during feature work. Tasks are added by
 implementation agents as they encounter opportunities. Reviewed and prioritized
 by the coordinator periodically.
 EOF
-bd create --title="Refactoring & DRY Opportunities" --type=epic --priority=3 -d "$(cat /tmp/refactor-epic-desc.md)"
+bd create --title="Refactoring & DRY Opportunities" --type=epic --priority=3 --body-file "$SCRATCH/refactor-epic-desc.md"
 ```
 
 This epic is **project-wide and long-lived** — it persists across feature epics.
@@ -604,8 +605,9 @@ Include in each option's description:
 
 - Path: `~/.workspaces/{repo}/{feature}` (from CLAUDE.md convention)
 - Branch: `feature/{feature-name}`, cut from the configured merge target
-  (`jq -r '.orchestration.merge_target' .thrum/config.json`) — never a
-  remembered branch name
+  (`CONFIG=.thrum/config.json; [ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"; jq -r '.orchestration.merge_target' "$CONFIG"`
+  — a worktree's `.thrum/` holds only a `redirect` file, not its own
+  `config.json`) — never a remembered branch name
 
 **For agent names**, suggest a name derived from the feature in each option
 description (e.g., `impl_{feature}`). The user can override.
@@ -626,8 +628,11 @@ git status
 # (rebase onto a moved base is banned project-wide; see CLAUDE.md
 # "Rebase onto current tip before sending MERGE-READY")
 # Resolve the branch, never hardcode it — a name in a document goes stale and
-# this one already did:
-TARGET=$(jq -r '.orchestration.merge_target' .thrum/config.json)
+# this one already did. Resolve through .thrum/redirect when present -- a
+# worktree's .thrum/ holds only a `redirect` file, not its own config.json:
+CONFIG=.thrum/config.json
+[ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"
+TARGET=$(jq -r '.orchestration.merge_target' "$CONFIG")
 git fetch origin "$TARGET"
 git merge "origin/$TARGET"
 # OR if branches diverged: ask user before merging
@@ -810,6 +815,7 @@ worktree-related values come from the Phase 3 assignments:
 | `{{EPIC_TITLE}}`       | Epic title (used in commit messages)                                                                                                                                                                                        |
 | `{{WORKTREE_PATH}}`    | **From Phase 3 worktree assignment**                                                                                                                                                                                        |
 | `{{BRANCH_NAME}}`      | **From Phase 3 worktree assignment**                                                                                                                                                                                        |
+| `{{BASE_BRANCH}}`      | Resolved from the project merge target: `CONFIG=.thrum/config.json; [ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"; jq -r '.orchestration.merge_target' "$CONFIG"` (a worktree's `.thrum/` holds only a `redirect` file). Never assume `main` |
 | `{{PROJECT_ROOT}}`     | Absolute path to the project root                                                                                                                                                                                           |
 | `{{DESIGN_DOC}}`       | **Absolute path** to the design spec                                                                                                                                                                                        |
 | `{{REFERENCE_CODE}}`   | Relevant reference code paths (relative OK if committed)                                                                                                                                                                    |