@chorus-aidlc/chorus 0.6.7 → 0.7.0

package/.next/standalone/public/install-codex.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+# Chorus + Codex CLI one-shot installer
+#
+# Usage:
+#   curl -sSL https://raw.githubusercontent.com/Chorus-AIDLC/Chorus/main/public/install-codex.sh | bash
+#   # or non-interactive:
+#   CHORUS_URL=https://... CHORUS_API_KEY=cho_... \
+#     bash <(curl -sSL https://raw.githubusercontent.com/Chorus-AIDLC/Chorus/main/public/install-codex.sh)
+#
+# What this does (idempotent, safe to re-run):
+#   1. Verifies `codex` CLI is installed.
+#   2. Registers (or upgrades) the Chorus plugin marketplace.
+#   3. Writes [mcp_servers.chorus] (url + Authorization header) and
+#      [plugins."chorus@chorus-plugins"] enabled = true into ~/.codex/config.toml,
+#      so Codex auto-enables the plugin on first launch (falls back to one-click
+#      `/plugins → Install` if auto-install does not fire).
+#   4. Installs a lazy hook wrapper under ~/.codex/hooks/chorus/ so Chorus hooks
+#      work even before the plugin cache is materialized.
+
+set -euo pipefail
+
+# ---------- cosmetics ----------
+BOLD=$'\033[1m'; DIM=$'\033[2m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RED=$'\033[31m'; RESET=$'\033[0m'
+ok()   { printf "${GREEN}✓${RESET} %s\n" "$*"; }
+warn() { printf "${YELLOW}!${RESET} %s\n" "$*" >&2; }
+die()  { printf "${RED}✗${RESET} %s\n" "$*" >&2; exit 1; }
+hdr()  { printf "\n${BOLD}%s${RESET}\n" "$*"; }
+
+# ---------- config ----------
+MARKETPLACE_NAME="chorus-plugins"
+MARKETPLACE_SOURCE_DEFAULT="${CHORUS_MARKETPLACE_SOURCE:-https://github.com/Chorus-AIDLC/Chorus}"
+CHORUS_URL_DEFAULT="${CHORUS_URL_DEFAULT:-http://localhost:8637/api/mcp}"
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+CONFIG_TOML="$CODEX_HOME/config.toml"
+
+is_tty() { [ -t 0 ] && [ -t 1 ]; }
+
+# If piped through `curl | bash`, stdin is the script body. Re-open from /dev/tty
+# so interactive prompts still work — but only if a real TTY is available AND we
+# actually need to prompt for input. Both CHORUS_URL and CHORUS_API_KEY being set
+# lets us run fully non-interactively (useful in CI or unified-exec sandboxes).
+if [ -z "${CHORUS_API_KEY:-}" ] && ! is_tty; then
+  if [ -r /dev/tty ] && [ -w /dev/tty ]; then
+    exec < /dev/tty
+  fi
+fi
+
+# ---------- step 1: check codex ----------
+hdr "1/5  Checking Codex CLI"
+command -v codex >/dev/null 2>&1 || die "codex not found in PATH. Install it first: npm i -g @openai/codex"
+ok "Found $(codex --version 2>/dev/null | head -1)"
+
+# ---------- step 2: register marketplace ----------
+hdr "2/5  Registering the Chorus plugin marketplace"
+# Extract the currently registered source (if any) for chorus-plugins.
+# awk scoped between the matching [marketplaces.<name>] header and the next [section].
+existing_source=""
+if [ -f "$CONFIG_TOML" ]; then
+  existing_source="$(awk -v name="$MARKETPLACE_NAME" '
+    $0 ~ "^\\[marketplaces\\." name "\\][[:space:]]*$" { in_block=1; next }
+    in_block && /^\[/              { in_block=0 }
+    in_block && /^source[[:space:]]*=/ {
+      sub(/^source[[:space:]]*=[[:space:]]*/, "")
+      gsub(/^"|"$/, "")
+      print
+      exit
+    }
+  ' "$CONFIG_TOML" 2>/dev/null || true)"
+fi
+
+if [ -z "$existing_source" ]; then
+  codex plugin marketplace add "$MARKETPLACE_SOURCE_DEFAULT" >/dev/null
+  ok "Added marketplace: $MARKETPLACE_SOURCE_DEFAULT"
+elif [ "$existing_source" = "$MARKETPLACE_SOURCE_DEFAULT" ]; then
+  # Same source — pull the latest plugin manifest/version.
+  if codex plugin marketplace upgrade "$MARKETPLACE_NAME" >/dev/null 2>&1; then
+    ok "Upgraded marketplace '${MARKETPLACE_NAME}' to latest"
+  else
+    warn "Marketplace '${MARKETPLACE_NAME}' already registered; upgrade skipped"
+  fi
+else
+  # Source changed — remove the stale registration and re-add.
+  warn "Marketplace '${MARKETPLACE_NAME}' points at a different source; re-registering"
+  warn "  old: $existing_source"
+  warn "  new: $MARKETPLACE_SOURCE_DEFAULT"
+  codex plugin marketplace remove "$MARKETPLACE_NAME" >/dev/null 2>&1 || true
+  codex plugin marketplace add "$MARKETPLACE_SOURCE_DEFAULT" >/dev/null
+  ok "Re-added marketplace: $MARKETPLACE_SOURCE_DEFAULT"
+fi
+
+# ---------- step 3: collect Chorus URL + API key ----------
+hdr "3/5  Configuring the Chorus MCP server"
+
+# URL
+if [ -n "${CHORUS_URL:-}" ]; then
+  url="$CHORUS_URL"
+  ok "Using CHORUS_URL from env: $url"
+elif [ -t 0 ]; then
+  printf "  Chorus MCP URL ${DIM}[default: $CHORUS_URL_DEFAULT]${RESET}: "
+  read -r url
+  url="${url:-$CHORUS_URL_DEFAULT}"
+else
+  url="$CHORUS_URL_DEFAULT"
+  warn "No TTY and CHORUS_URL unset — using default: $url"
+fi
+
+# API key
+if [ -n "${CHORUS_API_KEY:-}" ]; then
+  apikey="$CHORUS_API_KEY"
+  ok "Using CHORUS_API_KEY from env"
+elif [ -t 0 ]; then
+  printf "  Chorus API key (starts with cho_): "
+  stty -echo 2>/dev/null || true
+  read -r apikey
+  stty echo 2>/dev/null || true
+  printf "\n"
+  [ -n "$apikey" ] || die "API key is required"
+else
+  die "No TTY and CHORUS_API_KEY unset — cannot continue"
+fi
+
+# Must be http(s).
+case "$url" in
+  http://*|https://*) ;;
+  *) die "URL must start with http:// or https:// — got: $url" ;;
+esac
+
+# Normalize: the Chorus MCP endpoint lives under /api/mcp. If the user gave us
+# just a host (or a host with trailing slash, or any path that doesn't already
+# end in /api/mcp), append it so the MCP handshake hits the right route.
+case "$url" in
+  */api/mcp) ;;
+  */api/mcp/) url="${url%/}" ;;
+  */) url="${url}api/mcp" ;;
+  *)  url="${url}/api/mcp" ;;
+esac
+ok "MCP endpoint: $url"
+
+# ---------- step 4: write config.toml ----------
+hdr "4/5  Writing ~/.codex/config.toml"
+mkdir -p "$CODEX_HOME"
+[ -f "$CONFIG_TOML" ] || touch "$CONFIG_TOML"
+
+# Back up once
+if [ ! -f "$CONFIG_TOML.chorus-bak" ]; then
+  cp "$CONFIG_TOML" "$CONFIG_TOML.chorus-bak"
+  ok "Backed up original config to ${CONFIG_TOML}.chorus-bak"
+fi
+
+# Remove any existing [mcp_servers.chorus] and [mcp_servers.chorus.*] sub-tables
+# (idempotent — old rotated keys / headers are wiped, then fresh section appended).
+# Pure awk so we do not require Python on the user's machine.
+tmp="$(mktemp "${TMPDIR:-/tmp}/chorus-config.XXXXXX")"
+awk '
+  # A TOML table header line. Match [mcp_servers.chorus] and any
+  # [mcp_servers.chorus.<subtable>], plus [plugins."chorus@chorus-plugins"],
+  # and suppress lines until the next [section] header appears.
+  /^\[mcp_servers\.chorus(\..*)?\][[:space:]]*$/           { skip = 1; next }
+  /^\[plugins\."chorus@chorus-plugins"\][[:space:]]*$/      { skip = 1; next }
+  /^\[/                                                      { skip = 0 }
+  skip != 1                                                   { print }
+' "$CONFIG_TOML" > "$tmp"
+mv "$tmp" "$CONFIG_TOML"
+
+# Ensure user-owned file mode 600 (contains secret).
+chmod 600 "$CONFIG_TOML"
+
+# Append [mcp_servers.chorus] with literal URL + Authorization header.
+# (Codex does NOT expand ${VAR}; the token is a literal string in the header.)
+cat >> "$CONFIG_TOML" <<TOML
+
+[mcp_servers.chorus]
+url = "${url}"
+
+[mcp_servers.chorus.http_headers]
+Authorization = "Bearer ${apikey}"
+
+[plugins."chorus@chorus-plugins"]
+enabled = true
+TOML
+
+ok "Wrote [mcp_servers.chorus] and [plugins.\"chorus@chorus-plugins\"] → ${CONFIG_TOML}"
+
+# ---------- step 5: install hooks ----------
+hdr "5/5  Installing Chorus hooks"
+
+# Install a tiny wrapper that lazily resolves the newest plugin cache at
+# hook-run time. This lets us write hooks.json BEFORE `/plugins → Install`
+# has materialized the plugin cache — first-run UX becomes truly one-shot.
+WRAPPER_DIR="$CODEX_HOME/hooks/chorus"
+WRAPPER="$WRAPPER_DIR/run-hook.sh"
+mkdir -p "$WRAPPER_DIR"
+cat > "$WRAPPER" <<'WRAP'
+#!/usr/bin/env bash
+# Chorus hook wrapper (installed by public/install-codex.sh).
+# Resolves the newest installed Chorus plugin version at runtime and execs
+# the named hook script from its hooks/ directory. Exits 0 (no-op) if the
+# plugin has not been installed yet, so Codex sessions still start cleanly.
+set -eu
+HOOK_NAME="${1:-}"
+if [ -z "$HOOK_NAME" ]; then
+  echo '{}' ; exit 0
+fi
+shift
+CODEX_HOME_RESOLVED="${CODEX_HOME:-$HOME/.codex}"
+PLUGIN_ROOT="$CODEX_HOME_RESOLVED/plugins/cache/chorus-plugins/chorus"
+if [ ! -d "$PLUGIN_ROOT" ]; then
+  echo '{}' ; exit 0
+fi
+VER="$(ls -1 "$PLUGIN_ROOT" 2>/dev/null | sort -V | tail -1)"
+if [ -z "$VER" ]; then
+  echo '{}' ; exit 0
+fi
+SCRIPT="$PLUGIN_ROOT/$VER/hooks/$HOOK_NAME"
+if [ ! -x "$SCRIPT" ]; then
+  if [ -f "$SCRIPT" ]; then
+    chmod +x "$SCRIPT" 2>/dev/null || true
+  else
+    echo '{}' ; exit 0
+  fi
+fi
+exec "$SCRIPT" "$@"
+WRAP
+chmod +x "$WRAPPER"
+ok "Installed hook wrapper → $WRAPPER"
+
+HOOKS_JSON="$CODEX_HOME/hooks.json"
+if [ -f "$HOOKS_JSON" ] && ! grep -q "hooks/chorus/run-hook.sh\|chorus-plugins/chorus" "$HOOKS_JSON" 2>/dev/null; then
+  warn "Found a non-Chorus $HOOKS_JSON — not overwriting."
+  warn "  Add Chorus hook entries manually (command = $WRAPPER on-session-start.sh | on-post-submit-proposal.sh | on-post-submit-for-verify.sh)."
+else
+  cat > "$HOOKS_JSON" <<HJSON
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          { "type": "command", "command": "$WRAPPER on-session-start.sh", "timeout": 20, "statusMessage": "Chorus: checkin" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*chorus_pm_submit_proposal",
+        "hooks": [
+          { "type": "command", "command": "$WRAPPER on-post-submit-proposal.sh", "timeout": 10 }
+        ]
+      },
+      {
+        "matcher": ".*chorus_submit_for_verify",
+        "hooks": [
+          { "type": "command", "command": "$WRAPPER on-post-submit-for-verify.sh", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}
+HJSON
+  ok "Wrote $HOOKS_JSON (routing through $WRAPPER)"
+fi
+
+# Enable the codex_hooks feature flag in config.toml (idempotent).
+if grep -qE "^\[features\]" "$CONFIG_TOML"; then
+  if ! grep -qE "^codex_hooks\s*=\s*true" "$CONFIG_TOML"; then
+    tmp="$(mktemp "${TMPDIR:-/tmp}/chorus-features.XXXXXX")"
+    awk '
+      /^\[features\][[:space:]]*$/ { print; print "codex_hooks = true"; inserted=1; next }
+      { print }
+    ' "$CONFIG_TOML" > "$tmp" && mv "$tmp" "$CONFIG_TOML"
+    ok "Added codex_hooks = true under existing [features]"
+  else
+    ok "codex_hooks feature flag already enabled"
+  fi
+else
+  cat >> "$CONFIG_TOML" <<'TFEAT'
+
+[features]
+codex_hooks = true
+TFEAT
+  ok "Appended [features] codex_hooks = true"
+fi
+
+# ---------- epilogue ----------
+hdr "Done."
+cat <<NEXT
+
+Start Codex — the plugin is registered as INSTALLED_BY_DEFAULT so it
+should activate on first launch:
+
+  ${BOLD}codex${RESET}
+
+If /plugins does not show "chorus" as installed on first launch, open it
+and click Install once (Codex has no \`plugin install\` CLI command yet,
+so one manual click is the fallback path).
+
+Verify anytime:
+  ${BOLD}codex mcp list${RESET}         # 'chorus' row, Auth = 'Bearer token'
+  ${BOLD}codex features list${RESET}    # codex_hooks + plugins both true
+
+Then in Codex type ${BOLD}\$chorus${RESET} (or \$develop, \$review, \$proposal, …) to
+activate a skill. To change your API key later, just re-run this installer.
+
+NEXT

package/.next/standalone/public/skill/chorus/SKILL.md

@@ -86,10 +86,26 @@ creates  analyzes     drafts PRD         codes &      reviews   closes
 
 | Role | Responsibility | MCP Tools |
 |------|---------------|-----------|
-| **PM Agent** | Analyze Ideas, create Proposals (PRD + Task drafts), manage documents | Public + `chorus_pm_*` + `chorus_*_idea` |
+| **PM Agent** | Analyze Ideas, create Proposals (PRD + Task drafts), manage documents | Public + `chorus_pm_*` + `chorus_*_idea` + `task:write` tools (claim/release/submit/report) |
 | **Developer Agent** | Claim Tasks, write code, report work, submit for verification | Public + `chorus_*_task` + `chorus_report_work` |
 | **Admin Agent** | Create projects/ideas, approve/reject proposals, verify tasks, manage lifecycle | Public + `chorus_admin_*` + PM + Developer tools |
 
+### Permissions
+
+Each agent's tool visibility is driven by a **permission set**, not by the role label alone. Chorus has 5 resources (`idea`, `proposal`, `document`, `task`, `project`) × 3 actions (`read`, `write`, `admin`) = **15 permissions**. Each permission-gated MCP tool declares a single required permission (see `<BASE_URL>/docs/MCP_TOOLS.md` for the full table).
+
+**Role presets** map to permission sets:
+
+| Preset | Permissions |
+|--------|-------------|
+| `developer_agent` | all `*:read` + `task:write` |
+| `pm_agent` | all `*:read` + `idea:write` + `proposal:write` + `document:write` + `task:write` + `project:write` |
+| `admin_agent` | all 15 permissions (every `read` + `write` + `admin`) |
+
+**Custom permissions** are also supported: when creating an agent you can pick a preset AND/OR add individual permissions. The effective permission set is the union. Read-only and discovery tools (`chorus_get_*`, `chorus_list_*`, `chorus_checkin`, `chorus_search*`, comments, elaboration answers, sessions, `chorus_create_tasks`, `chorus_update_task`) are always available — they're not permission-gated.
+
+> **Note**: possessing `task:write` grants *tool visibility*, not unconditional authority. Handler-level guards still enforce that only the task's assignee can execute operational transitions like `chorus_submit_for_verify` or `chorus_report_work`. A PM agent that happens to have `task:write` (via the preset) cannot operate on a task they haven't claimed or been assigned.
+
 ---
 
 ## Common Tools (All Roles)
@@ -125,9 +141,9 @@ Results can be filtered by project(s) using optional HTTP headers in your MCP co
 
 ### MCP Connection
 
-- MCP sessions expire after 30 minutes of **inactivity** (sliding window)
-- Each MCP request automatically renews the session
-- If you receive a "Session not found" error, reinitialize the MCP connection
+- The Chorus MCP endpoint is **stateless** — each HTTP request creates a fresh server instance, so there is no client-side session to keep alive
+- Supply your API Key in the `Authorization: Bearer cho_...` header on every request (your MCP client handles this automatically)
+- Horizontal scaling works out of the box; no sticky sessions required
 
 ### Project Groups
 
@@ -257,11 +273,14 @@ API Keys are created by the user in the Chorus Web UI.
 **Ask the user to:**
 1. Open the Chorus settings page (e.g., `http://localhost:8637/settings`)
 2. Click **Create API Key**
-3. Enter Agent name, select role (Developer / PM / Admin)
+3. Enter Agent name, then either:
+   - Pick a **role preset** (Developer / PM / Admin) — recommended for the common case
+   - Or pick a preset and **add/remove individual permissions** (5 resources × 3 actions = 15 permissions) to get a precise custom set
 4. Click create and **immediately copy the key** (shown only once)
 
 **Security notes:**
-- Each Agent should have its own API Key with the minimum required role
+- Each Agent should have its own API Key with the minimum required permissions
+- Presets are the fastest path; custom permissions let you grant narrowly (e.g. a dev agent that also needs `idea:write` to file bugs)
 - API Keys should not be committed to version control
 
 ### 2. MCP Server Configuration
@@ -297,19 +316,25 @@ chorus_checkin()
 
 If it fails, check: API Key correct (`cho_` prefix)? URL reachable? IDE restarted?
 
-### 4. Role-Specific Tool Access
-
-| Tool Prefix | Developer | PM | Admin |
-|-------------|-----------|------|-------|
-| `chorus_get_*` / `chorus_list_*` | Yes | Yes | Yes |
-| `chorus_checkin` | Yes | Yes | Yes |
-| `chorus_add_comment` / `chorus_get_comments` | Yes | Yes | Yes |
-| `chorus_claim_task` / `chorus_release_task` | Yes | No | Yes |
-| `chorus_update_task` / `chorus_submit_for_verify` | Yes | No | Yes |
-| `chorus_report_work` | Yes | No | Yes |
-| `chorus_claim_idea` / `chorus_release_idea` | No | Yes | Yes |
-| `chorus_pm_*` | No | Yes | Yes |
-| `chorus_admin_*` | No | No | Yes |
+### 4. Tool Access by Preset
+
+The table below shows default tool availability for each preset (no custom permissions). Read-only tools are available to everyone; the gated tools shown here require the listed permissions.
+
+| Tool Group | Required Permission | Developer | PM | Admin |
+|------------|--------------------|-----------|------|-------|
+| `chorus_get_*` / `chorus_list_*` / `chorus_search*` | (public, read) | Yes | Yes | Yes |
+| `chorus_checkin` | (public) | Yes | Yes | Yes |
+| `chorus_add_comment` / `chorus_get_comments` | (public) | Yes | Yes | Yes |
+| `chorus_update_task` (field edits + status) | (public; assignee required for status) | Yes | Yes | Yes |
+| `chorus_claim_task` / `chorus_release_task` / `chorus_submit_for_verify` / `chorus_report_work` / `chorus_report_criteria_self_check` | `task:write` | Yes | **Yes** (0.7.0+) | Yes |
+| `chorus_claim_idea` / `chorus_release_idea` / `chorus_move_idea` / `chorus_pm_create_idea` / `chorus_pm_*_elaboration` | `idea:write` | No | Yes | Yes |
+| `chorus_pm_create_proposal` / `chorus_pm_*_proposal` / `chorus_pm_*_draft` / `chorus_pm_create_tasks` / `chorus_pm_assign_task` / `chorus_*_task_dependency` | `proposal:write` | No | Yes | Yes |
+| `chorus_pm_create_document` / `chorus_pm_update_document` | `document:write` | No | Yes | Yes |
+| `chorus_admin_create_project` / `chorus_admin_*_project_group` / `chorus_admin_move_project_to_group` | `project:write` | No | **Yes** (0.7.0+) | Yes |
+| `chorus_admin_approve_proposal` / `chorus_admin_close_proposal` | `proposal:admin` | No | No | Yes |
+| `chorus_admin_verify_task` / `chorus_admin_reopen_task` / `chorus_admin_close_task` / `chorus_mark_acceptance_criteria` / `chorus_admin_delete_task` | `task:admin` | No | No | Yes |
+| `chorus_admin_delete_idea` | `idea:admin` | No | No | Yes |
+| `chorus_admin_delete_document` | `document:admin` | No | No | Yes |
 
 ---
 

package/.next/standalone/public/skill/proposal-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.2.0"
+  version: "0.2.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -244,7 +244,7 @@ chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uu
 ```
 
 - Task should be `open` or `assigned`
-- Target agent should have `developer` or `developer_agent` role
+- Target agent must have `task: ["write"]` permission
 
 ---
 

package/.next/standalone/public/skill/quick-dev-chorus/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quick-dev-chorus
-version: 0.1.0
+version: 0.1.1
 description: Quick Task workflow — skip Idea→Proposal, create tasks directly, execute, and verify.
 ---
 
@@ -37,7 +37,7 @@ For complex work, consider using the idea and proposal skills instead.
 
 ## Pre-Flight: Admin Self-Verify Check
 
-**Before creating tasks**, if you have the `admin_agent` role, ask the user:
+**Before creating tasks**, if `chorus_checkin().agent.permissions.task` includes `"admin"`, ask the user:
 
 > "I have admin privileges. After development, should I verify the task myself, or leave it for another admin to verify?"
 
@@ -143,7 +143,7 @@ chorus_submit_for_verify({
 })
 ```
 
-**Admin self-verification:** If you have the `admin_agent` role and the user approved self-verification in the Pre-Flight check, you can verify the task yourself immediately after submitting:
+**Admin self-verification:** If you have `task: ["admin"]` in `permissions` and the user approved self-verification in the Pre-Flight check, you can verify the task yourself immediately after submitting:
 
 ```
 chorus_admin_verify_task({ taskUuid: "<task-uuid>" })

package/.next/standalone/public/test-install-codex.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# Test public/install-codex.sh for macOS bash 3.2 compatibility.
+#
+# Usage:
+#   bash public/test-install-codex.sh
+#   BASH32=/path/to/bash-3.2 bash public/test-install-codex.sh
+#
+# Picks a bash: $BASH32 → /tmp/bash32-build/bash-3.2/bash (hand-built)
+#              → /bin/bash (macOS system bash is 3.2.57)
+#              → `bash` on PATH.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SCRIPT="$REPO_ROOT/public/install-codex.sh"
+
+if [ -n "${BASH32:-}" ] && [ -x "$BASH32" ]; then
+  TEST_BASH="$BASH32"
+elif [ -x "/tmp/bash32-build/bash-3.2/bash" ]; then
+  TEST_BASH="/tmp/bash32-build/bash-3.2/bash"
+elif [ -x "/bin/bash" ]; then
+  TEST_BASH="/bin/bash"
+else
+  TEST_BASH="$(command -v bash)"
+fi
+
+BOLD=$'\033[1m'; GREEN=$'\033[32m'; RED=$'\033[31m'; DIM=$'\033[2m'; RESET=$'\033[0m'
+
+PASS=0; FAIL=0; FAIL_NOTES=""
+
+pass() { printf "  ${GREEN}PASS${RESET}  %s\n" "$*"; PASS=$((PASS + 1)); }
+fail() { printf "  ${RED}FAIL${RESET}  %s\n" "$*"; FAIL=$((FAIL + 1)); FAIL_NOTES="$FAIL_NOTES
+  - $*"; }
+
+echo "${BOLD}Testing:${RESET} $SCRIPT"
+echo "${BOLD}Using:${RESET}   $TEST_BASH ($("$TEST_BASH" --version | head -1))"
+echo ""
+
+# [1/4] Static scan — reject bash 4+ constructs
+echo "${BOLD}[1/4]${RESET} Static scan for bash 4+ constructs"
+scan() {
+  local label="$1"; local pattern="$2"
+  if grep -nE "$pattern" "$SCRIPT" >/tmp/install-codex-scan.$$ 2>/dev/null; then
+    fail "$label"
+    sed 's/^/         /' /tmp/install-codex-scan.$$
+  else
+    pass "$label"
+  fi
+  rm -f /tmp/install-codex-scan.$$
+}
+scan 'no ${VAR,,} / ${VAR^^} case conversion' '\$\{[A-Za-z_][A-Za-z0-9_]*(\[[^]]+\])?[,^]{1,2}\}'
+scan 'no "declare -A" / "typeset -A"'         '^[[:space:]]*(declare|typeset|local)[[:space:]]+-[A-Za-z]*A'
+scan 'no mapfile / readarray'                 '^\s*(mapfile|readarray)\b'
+scan 'no "&>" redirection'                    '[^|]&>[^>]'
+scan 'no "|&" redirection'                    '\|&'
+scan 'no ";;&" case fallthrough'              ';;&'
+
+# [2/4] Parse
+echo ""
+echo "${BOLD}[2/4]${RESET} Parse with $TEST_BASH -n"
+if "$TEST_BASH" -n "$SCRIPT" 2>/tmp/install-codex-parse.$$; then
+  pass "parses without syntax errors"
+else
+  fail "parse error"
+  sed 's/^/         /' /tmp/install-codex-parse.$$
+fi
+rm -f /tmp/install-codex-parse.$$
+
+# [3/4] End-to-end dry run with an isolated CODEX_HOME
+echo ""
+echo "${BOLD}[3/4]${RESET} End-to-end dry run (isolated CODEX_HOME)"
+
+TMP_HOME="$(mktemp -d -t chorus-install-test.XXXXXX)"
+trap 'rm -rf "$TMP_HOME"' EXIT
+
+FAKE_BIN="$TMP_HOME/bin"
+mkdir -p "$FAKE_BIN"
+cat > "$FAKE_BIN/codex" <<'FAKE'
+#!/usr/bin/env bash
+case "${1:-}" in
+  --version) echo "codex 0.125.0-test" ;;
+  plugin)
+    if [ "${2:-}" = "marketplace" ] && [ "${3:-}" = "list" ]; then
+      echo ""
+      exit 0
+    fi
+    exit 0
+    ;;
+  *) exit 0 ;;
+esac
+FAKE
+chmod +x "$FAKE_BIN/codex"
+
+run_out="$TMP_HOME/run.log"
+set +e
+env \
+  PATH="$FAKE_BIN:$PATH" \
+  HOME="$TMP_HOME" \
+  CODEX_HOME="$TMP_HOME/.codex" \
+  CHORUS_URL="https://chorus.test/api/mcp" \
+  CHORUS_API_KEY="cho_test_key_abc123" \
+  CHORUS_MARKETPLACE_SOURCE="https://github.com/Chorus-AIDLC/Chorus" \
+  "$TEST_BASH" "$SCRIPT" >"$run_out" 2>&1
+rc=$?
+set -e
+
+if [ "$rc" -ne 0 ]; then
+  fail "installer exited non-zero ($rc)"
+  sed 's/^/         /' "$run_out"
+else
+  pass "installer exited 0"
+fi
+
+cfg="$TMP_HOME/.codex/config.toml"
+if [ ! -f "$cfg" ]; then
+  fail "config.toml not created at $cfg"
+else
+  pass "config.toml created"
+  grep -q '^\[mcp_servers\.chorus\]' "$cfg" && pass "[mcp_servers.chorus] block present" || fail "[mcp_servers.chorus] missing"
+  grep -q 'url = "https://chorus.test/api/mcp"' "$cfg" && pass "url written literally" || fail "url not literal"
+  grep -q 'Authorization = "Bearer cho_test_key_abc123"' "$cfg" && pass "Authorization header literal" || fail "Authorization not literal"
+  if command -v stat >/dev/null 2>&1; then
+    mode="$(stat -c '%a' "$cfg" 2>/dev/null || stat -f '%OLp' "$cfg" 2>/dev/null || echo "")"
+    if [ "$mode" = "600" ]; then
+      pass "config.toml mode=600"
+    elif [ -n "$mode" ]; then
+      fail "config.toml mode=$mode (expected 600)"
+    fi
+  fi
+fi
+
+# [4/4] Idempotent re-run with a rotated key
+echo ""
+echo "${BOLD}[4/4]${RESET} Idempotent re-run with a rotated key"
+set +e
+env \
+  PATH="$FAKE_BIN:$PATH" \
+  HOME="$TMP_HOME" \
+  CODEX_HOME="$TMP_HOME/.codex" \
+  CHORUS_URL="https://chorus.test/api/mcp" \
+  CHORUS_API_KEY="cho_rotated_key_xyz789" \
+  "$TEST_BASH" "$SCRIPT" >"$run_out" 2>&1
+rc=$?
+set -e
+[ "$rc" -eq 0 ] && pass "rerun exited 0" || { fail "rerun exited non-zero ($rc)"; sed 's/^/         /' "$run_out"; }
+
+blocks="$(grep -c '^\[mcp_servers\.chorus\]' "$cfg" 2>/dev/null || echo 0)"
+[ "$blocks" = "1" ] && pass "exactly one [mcp_servers.chorus] block" || fail "found $blocks [mcp_servers.chorus] blocks"
+
+hdr_blocks="$(grep -c '^\[mcp_servers\.chorus\.http_headers\]' "$cfg" 2>/dev/null || echo 0)"
+[ "$hdr_blocks" = "1" ] && pass "exactly one [mcp_servers.chorus.http_headers] block" || fail "found $hdr_blocks http_headers blocks"
+
+if grep -q 'Authorization = "Bearer cho_rotated_key_xyz789"' "$cfg" && ! grep -q 'cho_test_key_abc123' "$cfg"; then
+  pass "rotated key replaced the previous key"
+else
+  fail "rotated key not applied cleanly"
+fi
+
+echo ""
+echo "${BOLD}Summary:${RESET} $PASS passed, $FAIL failed"
+if [ "$FAIL" -gt 0 ]; then
+  printf "${RED}%s${RESET}\n" "$FAIL_NOTES"
+  exit 1
+fi
+echo "${GREEN}All checks passed.${RESET}"