@chorus-aidlc/chorus 0.17.3 → 0.18.1

package/.next/standalone/public/chorus-plugin/bin/on-post-verify-task.sh

@@ -317,8 +317,8 @@ All tasks of idea-rooted proposal ${PROPOSAL_UUID} are now done. This is the fin
 
 ACTION REQUESTED: spawn code-reviewer for this idea — an independent, read-only review of the idea's AGGREGATE code change (the whole feature across all its tasks), not a single task.
 
-1. Spawn the code-reviewer in FOREGROUND, passing it ideaUuid="${idea_uuid}" and the review round number (read prior code-review verdict comments on the idea to determine it). It reviews cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage, and overall code soundness, then posts ONE VERDICT comment on the idea.
-2. Read its VERDICT on the idea (chorus_get_comments targetType="idea").
+1. Spawn the code-reviewer and wait for its completion notification, passing it ideaUuid="${idea_uuid}" and the review round number (read prior code-review verdict comments on the idea to determine it). It reviews cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage, and overall code soundness, then posts ONE VERDICT comment on the idea.
+2. Read THIS round's VERDICT on the idea (chorus_get_comments targetType="idea") — the comment posted after your dispatch, not an earlier round's. The launch result is not the verdict; do not declare the feature shippable before you have read that comment. If it is missing, check what the reviewer did post: a comment reporting the round limit was reached, or any other explicit refusal to review, is a deliberate escalation — STOP: do not respawn, do not self-review, do not post a VERDICT of your own; leave it pending the human's decision. If it posted nothing at all, respawn once and apply this same check again to what the retry posts — an explicit refusal still means STOP; only a second true silence lets you review the idea's aggregate change yourself as a read-only pass and post the VERDICT. Absence is never a PASS.
 3. PASS / PASS WITH NOTES -> the feature may ship.
 4. FAIL -> the orchestrator invokes Quick Dev to create new tasks on the original approved proposal; never reopen completed tasks or apply untracked fixes. Group related small BLOCKERs by default and split only materially large or independently testable fixes.
 5. Re-run only after every fix task passes AC self-check, independent task review, and admin verification to done. A failed or cancelled fix stops the loop and escalates. Keep maxCodeReviewRounds authoritative.

package/.next/standalone/public/chorus-plugin/bin/on-pre-spawn-agent.sh

@@ -28,27 +28,35 @@ fi
 CHORUS_SESSION_ID=$(printf '%s' "$EVENT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null) || true
 export CHORUS_SESSION_ID
 
-# Try to extract subagent_type and name from the tool input
+# Try to extract subagent_type and name from the tool input.
+# `tool_input.name` does not exist on CC's Task tool today — it is read for
+# forward-compatibility and falls back to subagent_type, which is the value the
+# SubagentStart hook also receives as agent_type (and uses as the session name).
 AGENT_TYPE=""
 AGENT_NAME=""
 if [ -n "$EVENT" ]; then
   AGENT_TYPE=$(echo "$EVENT" | jq -r '.tool_input.subagent_type // .input.subagent_type // empty' 2>/dev/null) || true
   AGENT_NAME=$(echo "$EVENT" | jq -r '.tool_input.name // .input.name // empty' 2>/dev/null) || true
 fi
+AGENT_NAME="${AGENT_NAME:-$AGENT_TYPE}"
 
-# Skip non-worker types — no need to remind for Explore/Plan agents
+# Skip non-worker types — no need to remind for Explore/Plan agents.
+# This list MUST stay identical to the skip list in on-subagent-start.sh:
+# a type skipped by only one hook leaves an orphan pending file that a later
+# internal/cleanup agent could FIFO-claim, defeating the spawn gate.
 case "$(printf '%s' "$AGENT_TYPE" | tr '[:upper:]' '[:lower:]')" in
-  explore|plan|haiku|claude-code-guide|statusline-setup)
+  explore|plan|haiku|claude-code-guide|statusline-setup|chorus:proposal-reviewer|chorus:task-reviewer)
     exit 0
     ;;
 esac
 
 # Write a per-agent pending file for SubagentStart to claim.
-# SubagentStart only receives agent_id + agent_type — not the name.
-# CC sometimes uses the agent name as agent_type, so we store both.
+#
+# The pending file is a SPAWN GATE, not a name channel: its presence proves a
+# SubagentStart came from a real Task spawn. The session name is derived by
+# on-subagent-start.sh from the event's own agent_type, never from this file.
 #
 # Each spawn gets its own file — no shared state, no concurrency issues.
-# File name is the agent name (or a unique fallback if name is empty).
 # SubagentStart claims by mv (atomic on same filesystem).
 #
 # CC may internally spawn cleanup agents that bypass PreToolUse:Task —
@@ -59,10 +67,15 @@ esac
 PENDING_DIR="${CHORUS_STATE_DIR:-${CLAUDE_PROJECT_DIR:-.}/.chorus}/pending"
 mkdir -p "$PENDING_DIR" 2>/dev/null || true
 
-# Use agent name as filename; fall back to timestamp-based unique name
-PENDING_NAME="${AGENT_NAME:-unknown-$(date +%s%N)}"
+# Filename stem: sanitized subagent_type (":" and "/" in namespaced types such as
+# chorus:code-reviewer become "_"), plus epoch seconds and the PID for uniqueness.
+# $$ is required: BSD date (macOS) has no %N, so two same-second spawns of the same
+# type would otherwise collide on a single filename and one would be lost.
+PENDING_STEM=$(printf '%s' "${AGENT_TYPE:-worker}" | tr -c '[:alnum:]._-' '_')
+[ -z "$PENDING_STEM" ] && PENDING_STEM="worker"
+PENDING_NAME="${PENDING_STEM}__$(date +%s)-$$"
 printf '{"name":"%s","type":"%s","ts":"%s"}\n' \
-  "${AGENT_NAME:-}" "${AGENT_TYPE:-}" "$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)" \
+  "${AGENT_NAME:-}" "${AGENT_TYPE:-}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   > "${PENDING_DIR}/${PENDING_NAME}"
 
 CONTEXT="[Chorus Plugin — Sub-agent Spawn]

package/.next/standalone/public/chorus-plugin/bin/on-session-start.sh

@@ -67,45 +67,17 @@ if command -v jq >/dev/null 2>&1; then
 
 fi
 
-# Detect OpenSpec mode for this repo, once per session.
-# Both conditions are required for OpenSpec mode to be usable:
-#   (a) an openspec/ directory at the project root (this repo was inited via `openspec init`), AND
-#   (b) the `openspec` CLI on PATH (so we can `openspec new change`, `validate`, `archive`).
-# Overrides (precedence high -> low, first match wins):
-#   1. enableOpenSpec userConfig toggle (default true) — UI-level switch.
-#   2. CHORUS_OPENSPEC_MODE=off env var — env-level explicit opt-out.
-# When the folder is present but the CLI is missing, surface that as a
-# specific reason so the user-visible toast can hint at the install step
-# instead of silently falling back.
+# Resolve the active spec mode for this repo, once per session. The resolution
+# logic lives in resolve-spec-mode.sh (pure: env + filesystem only) so it can be
+# unit-tested — see bin/tests/test-spec-mode-resolution.sh. It sets SPEC_MODE,
+# SPEC_REASON, SPEC_FAIL, OPENSPEC_USABLE_REASON, OPENSPEC_HINT, CHORUS_OPENSPEC_ACTIVE.
 #
-# The inactive states split into two user-facing kinds:
-#   - OPENSPEC_OPTOUT=1 — the user explicitly turned OpenSpec off (plugin
-#     toggle or env var). Respect it: show a neutral note, no nag.
-#   - OPENSPEC_OPTOUT=0 — OpenSpec is simply not set up (no folder, or folder
-#     without the CLI). Point the user at `/chorus enable openspec`, which walks
-#     the actual install/init steps — the banner stays a one-liner.
+# Summary: an explicit CHORUS_SPEC_MODE (lite|openspec|off) wins; when UNSET,
+# OpenSpec stays the default whenever it is usable (openspec/ dir + CLI, not
+# disabled) and lite is the fallback only when OpenSpec is absent or disabled.
+# Legacy CHORUS_OPENSPEC_MODE=off still forces not-openspec (→ lite when unset).
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-OPENSPEC_HINT=""
-OPENSPEC_OPTOUT=0
-if [ "${CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC:-true}" != "true" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_OPTOUT=1
-  OPENSPEC_REASON="enableOpenSpec userConfig=false (plugin-level opt-out)"
-elif [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_OPTOUT=1
-  OPENSPEC_REASON="CHORUS_OPENSPEC_MODE=off (explicit opt-out)"
-elif [ ! -d "${PROJECT_ROOT}/openspec" ]; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_REASON="no openspec/ directory at ${PROJECT_ROOT}/openspec"
-elif ! command -v openspec >/dev/null 2>&1; then
-  CHORUS_OPENSPEC_ACTIVE=0
-  OPENSPEC_REASON="openspec/ directory present but \`openspec\` CLI not on PATH"
-  OPENSPEC_HINT="install with: npm i -g @fission-ai/openspec"
-else
-  CHORUS_OPENSPEC_ACTIVE=1
-  OPENSPEC_REASON="openspec/ directory + openspec CLI both present"
-fi
+. "${SCRIPT_DIR}/resolve-spec-mode.sh"
 
 # Build context for Claude (additionalContext)
 CONTEXT="# Chorus Plugin — Active
@@ -116,33 +88,33 @@ Chorus is connected at ${CHORUS_URL}. Session lifecycle hooks are enabled.
 
 ${CHECKIN_RESULT}
 
-## OpenSpec Mode
+## Spec Mode
 
-CHORUS_OPENSPEC_ACTIVE=${CHORUS_OPENSPEC_ACTIVE} (${OPENSPEC_REASON})"
+CHORUS_SPEC_MODE=${SPEC_MODE} (${SPEC_REASON})"
 
-if [ "$CHORUS_OPENSPEC_ACTIVE" = "1" ]; then
+if [ "$SPEC_MODE" = "lite" ]; then
   CONTEXT="${CONTEXT}
 
-OpenSpec mode is **active** for this session. When the proposal / develop / yolo skills reach an OpenSpec-aware step, load the openspec-aware skill at \`.claude/skills/openspec-aware/SKILL.md\` and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.
+Routing: lite → follow the spec-lite skill (\`skills/spec-lite/SKILL.md\`). Author a Chorus-native change folder \`.chorus/specs/<slug>/\` (\`prd.md\` required; \`tech_design.md\` / \`adr.md\` / \`spec.md\` / \`guide.md\` optional) and mirror each \`<type>.md\` 1:1 into a Chorus Document of that type via \`chorus mcp call … --arg-file content=<file>\`. Do NOT scaffold \`openspec/changes/\` or add an \`OpenSpec change slug:\` line."
+elif [ "$SPEC_MODE" = "off" ]; then
+  CONTEXT="${CONTEXT}
 
-Critical rule (openspec-aware §2 Rule 1): document mirror calls (\`chorus_pm_add_document_draft\` / \`chorus_pm_update_document_draft\` / \`chorus_pm_update_document\`) MUST fill \`content\` from the local file — prefer \`chorus mcp call <tool> '<json>' --arg-file content=<file>\`, falling back to \`chorus-api.sh mcp-tool\` with \`json_encode_file\` when \`chorus\` is not on PATH. Do NOT invoke these MCP tools directly with hand-typed \`content\` in OpenSpec mode."
-else
+Routing: off → free-form, no spec artifact. Do NOT create \`.chorus/specs/\` or \`openspec/changes/\` files; author document drafts inline via direct MCP."
+elif [ -n "$SPEC_FAIL" ]; then
   CONTEXT="${CONTEXT}
 
-OpenSpec mode is **inactive** for this session. The proposal / develop / yolo skills follow their free-form path; do NOT scaffold \`openspec/changes/\`, do NOT add an \`OpenSpec change slug:\` line to proposal descriptions, and do NOT route document mirror calls through the \`chorus\` CLI or \`chorus-api.sh\`."
-  if [ "$OPENSPEC_OPTOUT" = "1" ]; then
-    CONTEXT="${CONTEXT}
+Routing: openspec → **cannot be honored** — ${SPEC_FAIL}. The proposal / yolo skill MUST halt after resolving the mode; do NOT silently fall back to lite/free-form. Surface this to the user."
+  if [ -n "$OPENSPEC_HINT" ]; then
+    CONTEXT="${CONTEXT} Install hint: ${OPENSPEC_HINT}."
+  fi
+else
+  CONTEXT="${CONTEXT}
 
-OpenSpec was **explicitly turned off** (${OPENSPEC_REASON}), so this is a deliberate choice — do NOT nag the user to enable it. If they ask to turn it back on, point them at re-enabling the plugin's \`enableOpenSpec\` toggle / unsetting \`CHORUS_OPENSPEC_MODE\`, then the OpenSpec setup section in the \`/chorus\` skill."
-  elif [ -n "$OPENSPEC_HINT" ]; then
-    CONTEXT="${CONTEXT}
+CHORUS_OPENSPEC_ACTIVE=1 (${OPENSPEC_USABLE_REASON})
 
-Note: this repo has an \`openspec/\` directory, so the user likely intends to use OpenSpec mode but the \`openspec\` CLI is not installed. Surface this to the user (e.g. \"This repo is OpenSpec-init'd but the \\\`openspec\\\` CLI isn't installed locally — ${OPENSPEC_HINT}\") before authoring documents. To set it up, run \`/chorus enable openspec\` (§6 walks the install + re-launch)."
-  else
-    CONTEXT="${CONTEXT}
+Routing: openspec → load the openspec-aware skill at \`.claude/skills/openspec-aware/SKILL.md\` and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.
 
-Note: OpenSpec is not set up in this repo (${OPENSPEC_REASON}). Spec-driven authoring is optional — free-form works fine. If the user wants spec-driven mode (proposal.md / design.md / spec deltas mirrored into Chorus), run \`/chorus enable openspec\` — §6 walks the \`npm i -g @fission-ai/openspec\` + \`openspec init\` steps and the re-launch."
-  fi
+Critical rule (openspec-aware §2 Rule 1): document mirror calls (\`chorus_pm_add_document_draft\` / \`chorus_pm_update_document_draft\` / \`chorus_pm_update_document\`) MUST fill \`content\` from the local file — prefer \`chorus mcp call <tool> '<json>' --arg-file content=<file>\`, falling back to \`chorus-api.sh mcp-tool\` with \`json_encode_file\` when \`chorus\` is not on PATH. Do NOT invoke these MCP tools directly with hand-typed \`content\` in OpenSpec mode."
 fi
 
 CONTEXT="${CONTEXT}
@@ -164,18 +136,21 @@ Resuming with existing Chorus session: ${MAIN_SESSION}"
   "$API" mcp-tool "chorus_session_heartbeat" "$(printf '{"sessionUuid":"%s"}' "$MAIN_SESSION")" >/dev/null 2>&1 || true
 fi
 
-# Build user-visible message. When OpenSpec is off-but-enable-able, point the
-# user at `/chorus enable openspec` — the skill walks the actual install/init.
-#   active            -> (OpenSpec Enabled)
-#   not set up        -> (OpenSpec off — run `/chorus enable openspec` to set it up)
-#   explicit opt-out  -> (OpenSpec off)  [neutral, no nag — respects the choice]
+# Build user-visible message. Always states the active spec mode (lite is the
+# default); an explicit openspec that can't be honored is flagged as not usable.
+#   lite              -> (Spec: lite)
+#   off               -> (Spec: off)
+#   openspec (usable) -> (Spec: openspec)
+#   openspec (broken) -> (Spec: openspec — not usable)
 USER_MSG="Chorus connected at ${CHORUS_URL}"
-if [ "$CHORUS_OPENSPEC_ACTIVE" = "1" ]; then
-  USER_MSG="${USER_MSG} (OpenSpec Enabled)"
-elif [ "$OPENSPEC_OPTOUT" = "1" ]; then
-  USER_MSG="${USER_MSG} (OpenSpec off)"
+if [ "$SPEC_MODE" = "lite" ]; then
+  USER_MSG="${USER_MSG} (Spec: lite)"
+elif [ "$SPEC_MODE" = "off" ]; then
+  USER_MSG="${USER_MSG} (Spec: off)"
+elif [ -n "$SPEC_FAIL" ]; then
+  USER_MSG="${USER_MSG} (Spec: openspec — not usable)"
 else
-  USER_MSG="${USER_MSG} (OpenSpec off — run \`/chorus enable openspec\` to set it up)"
+  USER_MSG="${USER_MSG} (Spec: openspec)"
 fi
 if [ -n "$MAIN_SESSION" ]; then
   USER_MSG="${USER_MSG} (resumed session)"

package/.next/standalone/public/chorus-plugin/bin/on-subagent-start.sh

@@ -2,8 +2,12 @@
 # on-subagent-start.sh — SubagentStart hook
 # Triggered SYNCHRONOUSLY when a sub-agent (teammate) is spawned.
 #
-# Name resolution: Claims a per-agent pending file written by PreToolUse:Task
-# using atomic mv (only one process can successfully mv a given file).
+# Name resolution: the session name is the event's own agent_type (the value the
+# spawning Task call passed as subagent_type), falling back to worker-<agentId8>.
+#
+# Spawn gate: claims a per-spawn pending file written by PreToolUse:Task using
+# atomic mv (only one process can successfully mv a given file). The file only
+# proves the spawn was a real Task call — it never carries the name.
 #
 # Session reuse logic:
 #   1. List existing sessions via MCP
@@ -45,14 +49,14 @@ export CHORUS_SESSION_ID
 [ -f "${SCRIPT_DIR}/chorus-paths.sh" ] && { . "${SCRIPT_DIR}/chorus-paths.sh" 2>/dev/null || true; }
 CHORUS_STATE_DIR="${CHORUS_STATE_DIR:-${CLAUDE_PROJECT_DIR:-.}/.chorus}"
 
-# Extract agent info from event
-# Note: SubagentStart only provides agent_id and agent_type — NOT the name
-# from the Task tool call. The name is captured by on-pre-spawn-agent.sh
-# (PreToolUse:Task) and stored as a per-agent file in .chorus/pending/.
+# Extract agent info from event.
+# agent_type is the same value the spawning Task call passed as subagent_type,
+# so it is the session name source (see SESSION_NAME below).
 AGENT_ID=$(echo "$EVENT" | jq -r '.agent_id // .agentId // empty' 2>/dev/null) || true
 AGENT_TYPE=$(echo "$EVENT" | jq -r '.agent_type // .agentType // empty' 2>/dev/null) || true
 
-# Skip non-worker agent types (read-only agents don't need sessions)
+# Skip non-worker agent types (read-only agents don't need sessions).
+# This list MUST stay identical to the skip list in on-pre-spawn-agent.sh.
 case "$(printf '%s' "$AGENT_TYPE" | tr '[:upper:]' '[:lower:]')" in
   explore|plan|haiku|claude-code-guide|statusline-setup|chorus:proposal-reviewer|chorus:task-reviewer)
     exit 0
@@ -66,35 +70,24 @@ fi
 # Claim a pending file written by PreToolUse:Task (on-pre-spawn-agent.sh).
 # Each pending file represents one expected sub-agent spawn.
 #
-# Claim strategy (atomic mv — only one process can succeed per file):
-#   1. Try exact match: mv .chorus/pending/{agent_type} → claimed/{agent_id}
-#      (CC often sets agent_type to the name from the Task tool call)
-#   2. Fallback: claim the oldest pending file (FIFO by modification time)
+# The pending file is a SPAWN GATE, not a name channel: it only proves this
+# SubagentStart corresponds to a real Task spawn. Neither its filename nor its
+# contents influence the session name, so plain FIFO claiming is safe even when a
+# mixed parallel batch pairs this agent with another spawn's file.
 #
-# If no pending file exists, this is an internal/cleanup agent → skip.
-AGENT_NAME=""
+# Claim strategy: FIFO by modification time, atomic mv (only one process can
+# succeed per file). If no pending file can be claimed, this is one of Claude
+# Code's internal/cleanup agents (they bypass PreToolUse:Task) → skip.
 PENDING_DIR="${CHORUS_STATE_DIR}/pending"
 CLAIMED_DIR="${CHORUS_STATE_DIR}/claimed"
 mkdir -p "$CLAIMED_DIR" 2>/dev/null || true
 
 CLAIMED_FILE=""
 
-# Strategy 1: exact match by agent_type (CC uses name as agent_type)
-if [ -f "${PENDING_DIR}/${AGENT_TYPE}" ]; then
-  if mv "${PENDING_DIR}/${AGENT_TYPE}" "${CLAIMED_DIR}/${AGENT_ID}" 2>/dev/null; then
-    CLAIMED_FILE="${CLAIMED_DIR}/${AGENT_ID}"
-    AGENT_NAME="$AGENT_TYPE"
-  fi
-fi
-
-# Strategy 2: FIFO — claim oldest pending file
-if [ -z "$CLAIMED_FILE" ] && [ -d "$PENDING_DIR" ]; then
+if [ -d "$PENDING_DIR" ]; then
   for candidate in $(ls -tr "$PENDING_DIR" 2>/dev/null); do
     if mv "${PENDING_DIR}/${candidate}" "${CLAIMED_DIR}/${AGENT_ID}" 2>/dev/null; then
       CLAIMED_FILE="${CLAIMED_DIR}/${AGENT_ID}"
-      # Read name from file content if available
-      FILE_NAME=$(jq -r '.name // empty' "$CLAIMED_FILE" 2>/dev/null) || true
-      AGENT_NAME="${FILE_NAME:-$candidate}"
       break
     fi
     # mv failed → another process claimed it first, try next
@@ -106,8 +99,17 @@ if [ -z "$CLAIMED_FILE" ]; then
   exit 0
 fi
 
-# Fallback: use agent_type + short ID if no name was captured
-SESSION_NAME="${AGENT_NAME:-${AGENT_TYPE:-worker}-${AGENT_ID:0:8}}"
+# Session name comes from this event's own agent_type (the same value the Task
+# call passed as subagent_type). Falls back to an agent-id-derived name only when
+# agent_type is empty — never a placeholder like "unknown-<digits>".
+SESSION_NAME="${AGENT_TYPE:-worker-${AGENT_ID:0:8}}"
+
+# Sanitized form for on-disk filenames only. Namespaced types such as
+# chorus:code-reviewer are not skipped, so they reach this path and must not put
+# a ":" or "/" into a path. The name sent to Chorus, the state keys and the
+# injected workflow text all keep the raw agent_type.
+SESSION_NAME_FILE=$(printf '%s' "$SESSION_NAME" | tr -c '[:alnum:]._-' '_')
+[ -z "$SESSION_NAME_FILE" ] && SESSION_NAME_FILE="worker-${AGENT_ID:0:8}"
 
 # === Session reuse: list existing sessions, find by name ===
 SESSION_UUID=""
@@ -187,11 +189,24 @@ fi
 "$API" state-set "session_${SESSION_NAME}" "$SESSION_UUID"
 "$API" state-set "name_for_agent_${AGENT_ID}" "$SESSION_NAME"
 
+# === Holder refcount: register this agent as a holder of the session NAME ===
+# Because the name is the repeating agent_type, two parallel sub-agents of the
+# same type converge on ONE session (reuse-by-name above). on-subagent-stop.sh
+# removes its own entry here and only tears the shared session down when no other
+# holder remains — otherwise the first sibling to exit would close the session,
+# check the other sibling's task out and delete state its sibling still reads.
+# Registered on every path (created / reused / reopened). The directory component
+# uses the SAME sanitization as the sessions/<name>.json filename — a namespaced
+# type such as chorus:code-reviewer must never put a ":" or "/" into a path.
+HOLDERS_DIR="${CHORUS_STATE_DIR}/holders/${SESSION_NAME_FILE}"
+mkdir -p "$HOLDERS_DIR" 2>/dev/null || true
+: > "${HOLDERS_DIR}/${AGENT_ID}" 2>/dev/null || true
+
 # === Session file: minimal metadata for other hooks (TeammateIdle, SubagentStop) ===
 SESSIONS_DIR="${CHORUS_STATE_DIR}/sessions"
 mkdir -p "$SESSIONS_DIR" 2>/dev/null || true
 
-cat > "${SESSIONS_DIR}/${SESSION_NAME}.json" <<SESSIONEOF
+cat > "${SESSIONS_DIR}/${SESSION_NAME_FILE}.json" <<SESSIONEOF
 {
   "sessionUuid": "${SESSION_UUID}",
   "agentId": "${AGENT_ID}",

package/.next/standalone/public/chorus-plugin/bin/on-subagent-stop.sh

@@ -4,6 +4,12 @@
 # Auto-checkout from all checked-in tasks, close the Chorus session,
 # clean up state files, and auto-verify if admin AC all passed.
 #
+# Holder-aware: session names are the repeating agent_type, so parallel same-type
+# sub-agents SHARE one session. Teardown (checkout / close / name-keyed state /
+# sessions file / auto-verify) only happens for the LAST holder of the name — see
+# the holder refcount block below. Non-last stops clean up only their own
+# id-keyed state and leave the session running for their siblings.
+#
 # NOTE: SubagentStop does NOT support additionalContext in Claude Code's
 # hookSpecificOutput schema, and systemMessage only reaches the UI —
 # not the main agent's LLM context. All agent-facing reminders must go
@@ -54,47 +60,104 @@ if [ -z "$SESSION_UUID" ]; then
   exit 0
 fi
 
-# === Auto-checkout from all checked-in tasks ===
+# Sanitized form of the name for on-disk paths (same tr sanitization as
+# on-subagent-start.sh uses for sessions/<name>.json and holders/<name>/) —
+# namespaced types such as chorus:code-reviewer must not put a ":" into a path.
+# The state keys keep the raw name.
+AGENT_NAME_FILE=""
+if [ -n "$AGENT_NAME" ]; then
+  AGENT_NAME_FILE=$(printf '%s' "$AGENT_NAME" | tr -c '[:alnum:]._-' '_')
+fi
+
+# === Holder refcount: is this the LAST agent holding the session name? ===
+# Session names are the repeating agent_type, so two parallel sub-agents of the
+# same type share ONE session (reuse-by-name in on-subagent-start.sh). Remove our
+# OWN holder entry first, then count what remains: only the last holder may close
+# the session, auto-checkout, auto-verify or delete the name-keyed state that
+# siblings (and on-teammate-idle.sh) still read.
+#
+# Races are benign and must stay benign: if a sibling's start has not registered
+# its holder yet we may see 0 holders and close the session; that sibling's start
+# then finds a closed/inactive row and reopens it via the existing reopen path.
+# Deliberately no locking.
+#
+# With no name in state we cannot refcount — fall back to the legacy
+# single-agent behaviour (treat this stop as the last holder).
+HOLDERS_DIR=""
+HOLDERS_REMAINING=0
+if [ -n "$AGENT_NAME_FILE" ]; then
+  HOLDERS_DIR="${CHORUS_STATE_DIR}/holders/${AGENT_NAME_FILE}"
+  rm -f "${HOLDERS_DIR}/${AGENT_ID}" 2>/dev/null || true
+  if [ -d "$HOLDERS_DIR" ]; then
+    HOLDERS_REMAINING=$(ls -1 "$HOLDERS_DIR" 2>/dev/null | grep -c . || true)
+  fi
+fi
+[ -n "$HOLDERS_REMAINING" ] || HOLDERS_REMAINING=0
+
+IS_LAST_HOLDER=true
+if [ "$HOLDERS_REMAINING" -gt 0 ]; then
+  IS_LAST_HOLDER=false
+fi
+
+# === Auto-checkout from all checked-in tasks (last holder only) ===
+# Open checkins on a shared session may belong to a still-running sibling, so a
+# non-last stop must not check them out — each sub-agent checks its own task out
+# per the workflow injected by on-subagent-start.sh.
 CHECKOUT_COUNT=0
-SESSION_DETAIL=$("$API" mcp-tool "chorus_get_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" 2>/dev/null) || true
+SESSION_DETAIL=""
+CLOSE_OK=true
 
-if [ -n "$SESSION_DETAIL" ]; then
-  TASK_UUIDS=$(echo "$SESSION_DETAIL" | jq -r '
-    .checkins[]? | select(.checkoutAt == null) | .taskUuid // empty
-  ' 2>/dev/null) || true
+if [ "$IS_LAST_HOLDER" = true ]; then
+  SESSION_DETAIL=$("$API" mcp-tool "chorus_get_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" 2>/dev/null) || true
 
-  if [ -z "$TASK_UUIDS" ]; then
+  if [ -n "$SESSION_DETAIL" ]; then
     TASK_UUIDS=$(echo "$SESSION_DETAIL" | jq -r '
-      .sessionTaskCheckins[]? | select(.checkoutAt == null) | .taskUuid // empty
+      .checkins[]? | select(.checkoutAt == null) | .taskUuid // empty
     ' 2>/dev/null) || true
-  fi
 
-  for TASK_UUID in $TASK_UUIDS; do
-    if [ -n "$TASK_UUID" ]; then
-      "$API" mcp-tool "chorus_session_checkout_task" \
-        "$(printf '{"sessionUuid":"%s","taskUuid":"%s"}' "$SESSION_UUID" "$TASK_UUID")" \
-        >/dev/null 2>&1 || true
-      CHECKOUT_COUNT=$((CHECKOUT_COUNT + 1))
+    if [ -z "$TASK_UUIDS" ]; then
+      TASK_UUIDS=$(echo "$SESSION_DETAIL" | jq -r '
+        .sessionTaskCheckins[]? | select(.checkoutAt == null) | .taskUuid // empty
+      ' 2>/dev/null) || true
     fi
-  done
-fi
 
-# Close the Chorus session via MCP
-CLOSE_OK=true
-"$API" mcp-tool "chorus_close_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" >/dev/null 2>&1 || CLOSE_OK=false
+    for TASK_UUID in $TASK_UUIDS; do
+      if [ -n "$TASK_UUID" ]; then
+        "$API" mcp-tool "chorus_session_checkout_task" \
+          "$(printf '{"sessionUuid":"%s","taskUuid":"%s"}' "$SESSION_UUID" "$TASK_UUID")" \
+          >/dev/null 2>&1 || true
+        CHECKOUT_COUNT=$((CHECKOUT_COUNT + 1))
+      fi
+    done
+  fi
 
-# Clean up state
+  # Close the Chorus session via MCP
+  "$API" mcp-tool "chorus_close_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" >/dev/null 2>&1 || CLOSE_OK=false
+fi
+
+# Clean up state.
+# The id-keyed keys are this agent's own and always go. The name-keyed mapping and
+# the reverse map agent_for_session_<uuid> (single-valued — siblings overwrite it)
+# are shared, so they only go on the last-holder path.
 "$API" state-delete "session_${AGENT_ID}" 2>/dev/null || true
-"$API" state-delete "agent_for_session_${SESSION_UUID}" 2>/dev/null || true
 "$API" state-delete "name_for_agent_${AGENT_ID}" 2>/dev/null || true
-if [ -n "$AGENT_NAME" ]; then
-  "$API" state-delete "session_${AGENT_NAME}" 2>/dev/null || true
+if [ "$IS_LAST_HOLDER" = true ]; then
+  "$API" state-delete "agent_for_session_${SESSION_UUID}" 2>/dev/null || true
+  if [ -n "$AGENT_NAME" ]; then
+    "$API" state-delete "session_${AGENT_NAME}" 2>/dev/null || true
+  fi
 fi
 
-# Clean up session file
+# Clean up session file + holder dir (last holder only — siblings still read
+# sessions/<name>.json, see on-teammate-idle.sh).
 SESSIONS_DIR="${CHORUS_STATE_DIR}/sessions"
-if [ -n "$AGENT_NAME" ] && [ -f "${SESSIONS_DIR}/${AGENT_NAME}.json" ]; then
-  rm -f "${SESSIONS_DIR}/${AGENT_NAME}.json"
+if [ "$IS_LAST_HOLDER" = true ]; then
+  if [ -n "$AGENT_NAME_FILE" ] && [ -f "${SESSIONS_DIR}/${AGENT_NAME_FILE}.json" ]; then
+    rm -f "${SESSIONS_DIR}/${AGENT_NAME_FILE}.json"
+  fi
+  if [ -n "$HOLDERS_DIR" ] && [ -d "$HOLDERS_DIR" ]; then
+    rmdir "$HOLDERS_DIR" 2>/dev/null || true
+  fi
 fi
 
 # Clean up claimed file (written by SubagentStart)
@@ -104,7 +167,9 @@ if [ -n "$AGENT_ID" ] && [ -f "${CLAIMED_DIR}/${AGENT_ID}" ]; then
 fi
 
 # === Auto-verify: if admin marked all AC, verify the task automatically ===
-if [ "$CLOSE_OK" = true ] && [ -n "$SESSION_DETAIL" ]; then
+# Last holder only: on a shared session the first checkin may belong to a sibling,
+# so a non-last stop must never auto-verify another agent's task.
+if [ "$IS_LAST_HOLDER" = true ] && [ "$CLOSE_OK" = true ] && [ -n "$SESSION_DETAIL" ]; then
   FIRST_TASK_UUID=$(echo "$SESSION_DETAIL" | jq -r '
     (.checkins // .sessionTaskCheckins // [])[] | .taskUuid // empty
   ' 2>/dev/null | head -1) || true
@@ -144,7 +209,13 @@ fi
 
 # === Output (UI-only, not visible to main agent LLM) ===
 DISPLAY_NAME="${AGENT_NAME:-${AGENT_ID:0:8}}"
-if [ "$CLOSE_OK" = true ]; then
+if [ "$IS_LAST_HOLDER" != true ]; then
+  # Shared session still has live holders — do not claim it was closed.
+  "$API" hook-output \
+    "Chorus session '${DISPLAY_NAME}' kept open (${HOLDERS_REMAINING} other agent(s) still using it)" \
+    "" \
+    "SubagentStop"
+elif [ "$CLOSE_OK" = true ]; then
   USER_MSG="Chorus session closed: '${DISPLAY_NAME}'"
   if [ "$CHECKOUT_COUNT" -gt 0 ]; then
     USER_MSG="${USER_MSG} (auto-checkout ${CHECKOUT_COUNT} task(s))"

package/.next/standalone/public/chorus-plugin/bin/resolve-spec-mode.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# resolve-spec-mode.sh — resolve the active Chorus spec mode for a repo.
+#
+# Pure (env + filesystem only; no network). Sourced by on-session-start.sh and
+# driven directly by tests/test-spec-mode-resolution.sh. Bash 3.2 compatible.
+#
+# Inputs (env):
+#   CHORUS_SPEC_MODE                    explicit override: lite | openspec | off (else unset)
+#   CHORUS_OPENSPEC_MODE                legacy opt-out: "off" disables OpenSpec
+#   CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC plugin toggle: "false" disables OpenSpec (default "true")
+#   PROJECT_ROOT                        repo root to probe for openspec/ (defaults to $PWD)
+#   command -v openspec                 OpenSpec CLI presence on PATH
+#
+# Outputs (vars set in the caller's shell when sourced):
+#   SPEC_MODE              lite | openspec | off      (value surfaced to Claude)
+#   SPEC_REASON            human-readable one-liner
+#   SPEC_FAIL              non-empty => stage skill MUST halt (unsatisfiable explicit openspec)
+#   OPENSPEC_USABLE        1 | 0
+#   OPENSPEC_USABLE_REASON human-readable
+#   OPENSPEC_HINT          install hint when OpenSpec is merely missing (else empty)
+#   CHORUS_OPENSPEC_ACTIVE 1 only when the resolved mode is a USABLE openspec
+#
+# Resolution (per owner): an explicit CHORUS_SPEC_MODE wins; when UNSET, OpenSpec
+# stays the default whenever it is usable (openspec/ dir + CLI, not disabled), and
+# lite is the fallback only when OpenSpec is absent or disabled.
+
+: "${PROJECT_ROOT:=$PWD}"
+
+# --- Is OpenSpec usable? (needs openspec/ dir + CLI on PATH + not disabled) ---
+OPENSPEC_DISABLED=0
+OPENSPEC_DISABLED_REASON=""
+if [ "${CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC:-true}" != "true" ]; then
+  OPENSPEC_DISABLED=1
+  OPENSPEC_DISABLED_REASON="enableOpenSpec userConfig=false (plugin-level opt-out)"
+elif [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
+  OPENSPEC_DISABLED=1
+  OPENSPEC_DISABLED_REASON="CHORUS_OPENSPEC_MODE=off (legacy opt-out)"
+fi
+
+OPENSPEC_USABLE=0
+OPENSPEC_USABLE_REASON=""
+OPENSPEC_HINT=""
+if [ "$OPENSPEC_DISABLED" = "1" ]; then
+  OPENSPEC_USABLE_REASON="$OPENSPEC_DISABLED_REASON"
+elif [ ! -d "${PROJECT_ROOT}/openspec" ]; then
+  OPENSPEC_USABLE_REASON="no openspec/ directory at ${PROJECT_ROOT}/openspec"
+  OPENSPEC_HINT="npm i -g @fission-ai/openspec && openspec init"
+elif ! command -v openspec >/dev/null 2>&1; then
+  OPENSPEC_USABLE_REASON="openspec/ directory present but \`openspec\` CLI not on PATH"
+  OPENSPEC_HINT="npm i -g @fission-ai/openspec"
+else
+  OPENSPEC_USABLE=1
+  OPENSPEC_USABLE_REASON="openspec/ directory + openspec CLI both present"
+fi
+
+# --- Resolve CHORUS_SPEC_MODE ---
+SPEC_FAIL=""
+case "${CHORUS_SPEC_MODE:-}" in
+  lite)
+    SPEC_MODE="lite"
+    SPEC_REASON="explicit — Chorus-native lightweight specs in .chorus/specs/<slug>/"
+    ;;
+  off)
+    SPEC_MODE="off"
+    SPEC_REASON="explicit — free-form, no spec artifact"
+    ;;
+  openspec)
+    SPEC_MODE="openspec"
+    if [ "$OPENSPEC_USABLE" = "1" ]; then
+      SPEC_REASON="explicit; ${OPENSPEC_USABLE_REASON}"
+    elif [ "$OPENSPEC_DISABLED" = "1" ]; then
+      SPEC_REASON="explicit, but OpenSpec is disabled: ${OPENSPEC_USABLE_REASON}"
+      SPEC_FAIL="config conflict — CHORUS_SPEC_MODE=openspec vs OpenSpec disabled (${OPENSPEC_USABLE_REASON}); re-enable OpenSpec or set CHORUS_SPEC_MODE=lite"
+    else
+      SPEC_REASON="explicit, but OpenSpec is not installed: ${OPENSPEC_USABLE_REASON}"
+      SPEC_FAIL="OpenSpec not usable (${OPENSPEC_USABLE_REASON})"
+    fi
+    ;;
+  "")
+    # Unset: OpenSpec is the default when usable; lite is the fallback otherwise.
+    if [ "$OPENSPEC_USABLE" = "1" ]; then
+      SPEC_MODE="openspec"
+      SPEC_REASON="default — ${OPENSPEC_USABLE_REASON}; set CHORUS_SPEC_MODE=lite for Chorus-native specs, =off to disable"
+    else
+      SPEC_MODE="lite"
+      SPEC_REASON="default — OpenSpec not usable (${OPENSPEC_USABLE_REASON}); using Chorus-native lightweight specs in .chorus/specs/<slug>/"
+    fi
+    ;;
+  *)
+    # Unrecognized value: treat like unset (OpenSpec-if-usable, else lite).
+    if [ "$OPENSPEC_USABLE" = "1" ]; then
+      SPEC_MODE="openspec"
+      SPEC_REASON="CHORUS_SPEC_MODE='${CHORUS_SPEC_MODE}' unrecognized; falling back to default (${OPENSPEC_USABLE_REASON})"
+    else
+      SPEC_MODE="lite"
+      SPEC_REASON="CHORUS_SPEC_MODE='${CHORUS_SPEC_MODE}' unrecognized; OpenSpec not usable, defaulting to lite"
+    fi
+    ;;
+esac
+
+# Back-compat flag for the openspec-aware skill: active only when the resolved
+# mode is a USABLE openspec.
+if [ "$SPEC_MODE" = "openspec" ] && [ -z "$SPEC_FAIL" ]; then
+  CHORUS_OPENSPEC_ACTIVE=1
+else
+  CHORUS_OPENSPEC_ACTIVE=0
+fi