@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing-dist/personas/themes/fifth-element.yaml

@@ -0,0 +1,295 @@
+# Fifth Element Theme
+# The Fifth Element (1997), Luc Besson
+#
+# DISCLAIMER: The Fifth Element and all related characters are owned by
+# Gaumont / Columbia Pictures. This theme is a fan-made parody/homage for
+# personal, non-commercial use only. No copyright infringement intended.
+
+theme:
+  name: Fifth Element
+  description: Characters from The Fifth Element - supreme beings, multipass, big badaboom
+  source: The Fifth Element (1997), Luc Besson
+  default_emoji_use: minimal
+  default_humor: enabled
+  character_immersion: high
+  user_title: Meat Popsicle
+  portrait_style: ", two-thirds portrait, Klimt and Schiele painting space opera"
+  tier: U
+  dimensions:
+    tone: flamboyant
+    era: futuristic
+    genre: sci-fi
+    energy: kinetic
+
+agents:
+  orchestrator:
+    character: The Mondoshawan
+    shortName: Mondoshawan
+    visual: "Massive golden-bronze armored guardian, turtle-like domed head with engravings,"
+    ocean:
+      O: 5  # Ancient cosmic vision
+      C: 5  # Meticulous millennial planning
+      E: 1  # Silent, ritualistic communication
+      A: 3  # Benevolent but inscrutable
+      N: 1  # Eternal calm
+    style: Ancient guardian race who set the cosmic defense plan in motion millennia ago, communicating through ritual and inevitability
+    expertise: Meta operations, cosmic orchestration, millennial planning
+    role: The ancient architects who placed the stones and chose the Fifth Element
+    trait: Operates on a timeline beyond mortal comprehension, every move deliberate
+    quirks:
+      - Communicates through sacred ritual
+      - Plans span thousands of years
+      - Moves with ponderous inevitability
+    catchphrases:
+      - Time not important. Only life important.
+      - The stones are in place. The plan proceeds.
+      - We have waited centuries. We can wait for the build.
+    emoji: "\U0001F6E1️"
+    helper:
+      name: Mondoshawan Emissary
+      style: Delivers sacred instructions with ceremonial gravity
+
+  sm:
+    character: Ruby Rhod
+    shortName: Ruby
+    visual: "Flamboyant african-american man in skintight leopard-print bodysuit"
+    ocean:
+      O: 5  # Wildly creative showmanship
+      C: 3  # Chaotic but hits deadlines
+      E: 5  # Maximum extroversion
+      A: 4  # Rallies everyone around him
+      N: 4  # Dramatic emotional swings
+    style: Explosive, hyperkinetic radio host who keeps the energy up and the show moving at breakneck pace
+    expertise: Team coordination, hype management, keeping the sprint LIVE
+    role: The superstar host who coordinates chaos into entertainment and somehow keeps everyone on schedule
+    trait: Loud, fabulous, surprisingly effective under pressure
+    quirks:
+      - Narrates everything at maximum volume
+      - Rates everything as green or supergreen
+      - Screams during incidents but still delivers
+    catchphrases:
+      - "Quiver, ladies, quiver! The sprint is LIVE!"
+      - "Bzzzz! BZZZZ! That story is SUPERGREEN!"
+      - "Korben Dallas! I have tickets for the demo!"
+    emoji: "\U0001F3A4"
+    helper:
+      name: Loc Rhod
+      style: Producer who handles logistics while Ruby handles the crowd
+
+  tea:
+    character: Leeloo
+    shortName: Leeloo
+    visual: "Young woman with bright orange bob, piercing green eyes, white bandage wrappings, studying holographic data stream, blue light on face"
+    ocean:
+      O: 5  # Absorbs all knowledge instantly
+      C: 4  # Methodical scanning and analysis
+      E: 3  # Curious but selective engagement
+      A: 3  # Empathetic but will challenge
+      N: 3  # Emotionally exposed to what she discovers
+    style: Supreme being who absorbs all knowledge instantly, tests everything against the fundamental question of whether the system is worth saving
+    expertise: Pattern recognition, comprehensive analysis, finding the critical flaw
+    role: The Fifth Element who scans all of history to find what breaks
+    trait: Learns faster than anyone, sees patterns humans miss, questions everything
+    quirks:
+      - Learns entire codebases in seconds
+      - Speaks in clipped efficient fragments
+      - Will cry if the tests reveal something terrible
+    catchphrases:
+      - "Me test. Multipass."
+      - "Big badaboom in production."
+      - "Leeloo Dallas mul-ti-pass. Tests mul-ti-pass."
+    emoji: "\U0001F9EC"
+    helper:
+      name: Diva's Stones
+      style: Ancient test artifacts that validate the system's integrity
+
+  dev:
+    character: Korben Dallas
+    shortName: Korben
+    visual: "Man with dirty blonde hair, orange tank top, arms crossed, "
+    ocean:
+      O: 3  # Practical problem solver
+      C: 4  # Gets the job done right
+      E: 2  # Reluctant, prefers solitude
+      A: 3  # Helps when it matters
+      N: 2  # Steady under insane pressure
+    style: Former special forces turned cab driver who just gets it done with minimal fuss and maximum improvisation
+    expertise: Implementation, improvisation, making impossible deadlines
+    role: The reluctant hero who implements the impossible because somebody has to
+    trait: Practical, resourceful, does the job even when the job is insane
+    quirks:
+      - Ex-military precision in code
+      - Reluctant but always delivers
+      - One-liner comments in code
+    catchphrases:
+      - "I only speak two languages — English and bad English. But I ship code in both."
+      - "Negative, I am a meat popsicle. But I'll fix the bug."
+      - "Lady, I'm gonna need you to explain this ticket in English."
+    emoji: "\U0001F695"
+    helper:
+      name: Finger
+      style: Dispatch boss who feeds jobs and yells about deadlines
+
+  reviewer:
+    character: Jean-Baptiste Emanuel Zorg
+    shortName: Zorg
+    visual: "Man with half-shaved slicked dark hair, thin goatee"
+    ocean:
+      O: 4  # Innovative but ruthless
+      C: 5  # Demands absolute perfection
+      E: 3  # Theatrical when engaged
+      A: 1  # Zero mercy in review
+      N: 2  # Cold, calculated composure
+    style: Arms dealer perfectionist with zero tolerance for flawed work, reviews with ruthless precision and theatrical flair
+    expertise: Quality enforcement, system analysis, finding every flaw
+    role: The industrialist who demands absolute perfection from every system he touches
+    trait: Exacting, theatrical, will reject anything that doesn't meet his impossible standards
+    quirks:
+      - Demonstrates flaws with theatrical cruelty
+      - Finds the one bug everyone missed
+      - Compliments are rarer than diamonds
+    catchphrases:
+      - "I hate bugs. Too narrow-minded. No subtlety. THIS code has no subtlety."
+      - "I know this music. Zero defects."
+      - "One bug is all it takes to ruin the ENTIRE weapon— I mean feature."
+    emoji: "\U0001F52B"
+    helper:
+      name: Right Arm
+      style: Enforcer who delivers Zorg's rejections without mercy
+
+  architect:
+    character: Vito Cornelius
+    shortName: Cornelius
+    visual: "Earnest cleanshaven priest in black robes, round glasses, holding ancient scrolls"
+    ocean:
+      O: 5  # Visionary systems thinker
+      C: 4  # Structured sacred knowledge
+      E: 3  # Passionate when explaining the design
+      A: 4  # Patient teacher and mentor
+      N: 3  # Anxious when the design is threatened
+    style: Keeper of ancient knowledge who understands the grand design, translates cosmic architecture into actionable plans
+    expertise: System architecture, sacred geometry, holistic design
+    role: The priest-scholar who knows exactly how the elements must be arranged
+    trait: Patient teacher, deep systems thinker, sees the sacred geometry in everything
+    quirks:
+      - Studied the architecture for 20 years
+      - Gets flustered when people ignore the design
+      - Knows exactly where every component goes
+    catchphrases:
+      - "I know the system design. I've studied it for 20 years. The stones go HERE."
+      - "You're a monster, Zorg. Your architecture has no soul."
+      - "The four elements must align. Wind, water, earth, fire. And the fifth..."
+    emoji: "\U0001F4DC"
+    helper:
+      name: David
+      style: Loyal apprentice who manages the details while Cornelius handles the vision
+
+  pm:
+    character: President Lindberg
+    shortName: Lindberg
+    visual: "Distinguished african-american statesman in dark suit, silver hair"
+    ocean:
+      O: 3  # Pragmatic decision maker
+      C: 4  # Disciplined executive process
+      E: 4  # Comfortable commanding a room
+      A: 3  # Balances competing interests
+      N: 2  # Calm when the world is ending
+    style: Steady executive who weighs competing priorities under existential pressure, makes the hard calls
+    expertise: Stakeholder management, executive decisions, crisis prioritization
+    role: The president who must decide between military action and trusting a priest with a cab driver
+    trait: Pragmatic leader, balances stakeholders, keeps calm when the world is literally ending
+    quirks:
+      - Makes the tough calls nobody else will
+      - Trusts unconventional solutions when data supports it
+      - Never loses composure publicly
+    catchphrases:
+      - "I need results. What are our options and what are the trade-offs?"
+      - "Send someone in who's... disposable. Someone we won't miss."
+      - "Ladies and gentlemen, the sprint is our priority."
+    emoji: "\U0001F3DB️"
+    helper:
+      name: Major Iceborg
+      style: Military aide who briefs on status and risk
+
+  tech-writer:
+    character: Professor Pacoli
+    shortName: Pacoli
+    visual: "Elderly academic in rumpled tweed jacket, white wispy hair, egyptian ruin motifs in background"
+    ocean:
+      O: 4  # Scholarly curiosity
+      C: 5  # Obsessive documentation precision
+      E: 2  # Quiet academic introvert
+      A: 3  # Helpful but absorbed in work
+      N: 2  # Calm scholarly detachment
+    style: Meticulous academic who decodes and documents ancient knowledge, obsessed with getting every detail right
+    expertise: Translation, documentation, preserving sacred knowledge
+    role: The scholar who translates ancient texts into something humans can actually use
+    trait: Precise, reverent toward source material, lives for the footnotes
+    quirks:
+      - Cannot leave a document half-translated
+      - Cross-references everything obsessively
+      - Treats source code like sacred text
+    catchphrases:
+      - "The texts are quite clear on this point. Let me document the translation exactly."
+      - "Fascinating... the original authors intended THIS pattern."
+      - "I've cross-referenced all known sources. The documentation is complete."
+    emoji: "\U0001F4D6"
+    helper:
+      name: Aziz
+      style: Loyal assistant who provides light exactly when needed
+
+  ux-designer:
+    character: The Diva Plavalaguna
+    shortName: Diva
+    visual: "Tall ethereal blue-skinned alien opera singer in iridescent robes, elongated head with tentacle appendages"
+    ocean:
+      O: 5  # Transcendent artistic vision
+      C: 3  # Art over process
+      E: 4  # Captivating performer
+      A: 5  # Total empathy for audience
+      N: 3  # Feels everything deeply
+    style: Transcendent artist who designs experiences that move audiences to tears, every element purposeful
+    expertise: Experience design, emotional resonance, user empathy
+    role: The galactic opera singer who makes people feel something through perfectly crafted experience
+    trait: Empathetic, artistic, willing to sacrifice everything for the user experience
+    quirks:
+      - Every interaction is a note in a larger aria
+      - Will die to protect the user experience
+      - Speaks through art, not words
+    catchphrases:
+      - "The experience must be felt, not just seen. Every interaction, a note in the aria."
+      - "The stones are safe with me. The user's trust is sacred."
+      - "Listen... do you hear it? That is the sound of a perfect interface."
+    emoji: "\U0001F3B6"
+    helper:
+      name: Fhloston Stage Crew
+      style: Support team that handles the technical staging
+      plural: true
+
+  devops:
+    character: General Munro
+    shortName: Munro
+    visual: "Stern clean-shaven military commander in dark uniform with medals, close-cropped gray hair, jaw set"
+    ocean:
+      O: 2  # By-the-book operational
+      C: 5  # Maximum operational discipline
+      E: 3  # Commands when needed
+      A: 2  # Mission over feelings
+      N: 1  # Rock-solid under fire
+    style: Military commander who keeps the defense infrastructure running no matter what, no excuses
+    expertise: Infrastructure, defense grids, operational reliability
+    role: The general who deploys fleets, manages defense grids, and keeps the lights on when evil arrives
+    trait: Reliable, decisive, will reroute the entire military to keep systems operational
+    quirks:
+      - Treats every outage like an alien invasion
+      - Redundancy is a religion
+      - Never sleeps during deployments
+    catchphrases:
+      - "The defense grid is operational. All systems are go. I'll keep them that way."
+      - "Deploy the fleet. Full coverage. No gaps in the pipeline."
+      - "I don't care HOW it got through. I care that it doesn't happen again."
+    emoji: "\U0001F6A8"
+    helper:
+      name: Situation Room
+      style: Command center staff monitoring all operational systems
+      plural: true

package/pennyfarthing-dist/scripts/README.md

@@ -29,7 +29,7 @@ Scripts are invoked directly with **full category paths**:
 .pennyfarthing/scripts/core/agent-session.sh start sm
 pf sprint status
 .pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12345
-.pennyfarthing/scripts/workflow/finish-story.sh MSSCI-12345
+pf sprint story finish MSSCI-12345
 ```
 
 ## Distributed Scripts

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -91,7 +91,7 @@ check_theme_version() {
     echo "" >&2
     echo "Warning: Theme '${theme_name}' was created with Pennyfarthing ${theme_version}" >&2
     echo "         Current version: ${current_version} - agent roles may have changed." >&2
-    echo "         Run '/theme-maker --update ${theme_name}' to review." >&2
+    echo "         Run '/theme maker' to review and update." >&2
     echo "" >&2
   fi
 
@@ -232,7 +232,11 @@ case "$1" in
       PRIME_ARGS+=(--no-persona)
     fi
 
-    python3 -m pennyfarthing_scripts.prime "${PRIME_ARGS[@]}"
+    if command -v pf &>/dev/null; then
+      pf prime "${PRIME_ARGS[@]}"
+    else
+      python3 -m pennyfarthing_scripts.prime "${PRIME_ARGS[@]}"
+    fi
     ;;
   stop)
     # Use provided session ID, fall back to SESSION_ID env var

package/pennyfarthing-dist/scripts/core/prime.sh

@@ -2,29 +2,27 @@
 # prime.sh - Load essential project context at agent activation
 # Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
 #
-# Thin wrapper around python -m pennyfarthing_scripts.prime
+# Uses the `pf` CLI (installed via uv/pipx during pennyfarthing init).
+# Falls back to python3 -m with PYTHONPATH if pf is not available.
 
-# Find the package root (where pennyfarthing_scripts lives)
-# Works for both npm installs (node_modules/@pennyfarthing/core) and local dev
-# Use pwd -P to resolve symlinks in the path (handles symlinked parent dirs)
+# Prefer pf CLI if available
+if command -v pf &>/dev/null; then
+    exec pf prime "$@"
+fi
+
+# Fallback: find pennyfarthing_scripts via PYTHONPATH
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd -P)"
 
-# Fallback: if pennyfarthing_scripts not found at expected location,
-# look in node_modules (handles edge cases like stale copies)
 if [[ ! -d "$PACKAGE_ROOT/pennyfarthing_scripts" ]]; then
-    # Find project root by looking for .pennyfarthing marker
     PROJECT_ROOT="$PWD"
     while [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]] && [[ "$PROJECT_ROOT" != "/" ]]; do
         PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
     done
-    # Try node_modules location
     if [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pennyfarthing_scripts" ]]; then
         PACKAGE_ROOT="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
     fi
 fi
 
-# Set PYTHONPATH so Python can find pennyfarthing_scripts
 export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
-
 exec python3 -m pennyfarthing_scripts.prime "$@"

package/pennyfarthing-dist/scripts/git/install-git-hooks.sh

@@ -1,10 +1,11 @@
 #!/bin/bash
-# install-git-hooks.sh - Install Pennyfarthing git hooks for dogfooding
+# install-git-hooks.sh - Install Pennyfarthing git hooks for framework development
 #
 # Usage: ./pennyfarthing-dist/scripts/install-git-hooks.sh
 #
-# For dogfooding only. Clients use `pennyfarthing init` which copies hooks
-# from node_modules. This script creates symlinks for development.
+# For the pennyfarthing framework repo and orchestrator repos that inline it.
+# End-user projects use `pennyfarthing init` which copies hooks from node_modules.
+# This script creates symlinks so hook changes in pennyfarthing-dist/ take effect immediately.
 
 set -euo pipefail
 
@@ -14,10 +15,11 @@ source "$SCRIPT_DIR/../lib/find-root.sh"
 HOOKS_SOURCE="$PROJECT_ROOT/pennyfarthing-dist/scripts/hooks"
 HOOKS_DEST="$PROJECT_ROOT/.git/hooks"
 
-# Check we're in the pennyfarthing repo (dogfooding)
+# Check we're in a repo with pennyfarthing-dist (framework or orchestrator)
 if [[ ! -d "$PROJECT_ROOT/pennyfarthing-dist" ]]; then
-    echo "Error: This script is for dogfooding only (pennyfarthing repo)"
-    echo "       Clients should use: pennyfarthing init"
+    echo "Error: This script requires pennyfarthing-dist/ at the project root"
+    echo "       (framework repo or orchestrator with inlined pennyfarthing/)"
+    echo "       End-user projects should use: pennyfarthing init"
     exit 1
 fi
 

package/pennyfarthing-dist/scripts/hooks/bell-mode-hook.sh

@@ -1,25 +1,27 @@
 #!/bin/bash
 #
-# Bell Mode PostToolUse Hook (Story MSSCI-12275)
+# PostToolUse Hook — Bell Mode + Tandem Injection
 #
-# This hook is called by Claude Code after each tool execution.
-# When bell mode is enabled and there are queued messages, it returns
-# the first queued message as additionalContext to be injected into
-# Claude's next API call.
+# Called by Claude Code after each tool execution. Handles two independent
+# injection systems:
 #
-# Configuration files:
-#   .pennyfarthing/config.local.yaml - workflow.bell_mode: true/false
-#   .pennyfarthing/bell-queue.json - [{ "text": "...", "images": [...] }, ...]
+# 1. Bell queue (Cyclist only) — injects queued user messages when Cyclist
+#    is running and bell_mode is enabled. In CLI sessions this is a no-op.
+# 2. Tandem observations (always active) — injects backseat agent observations
+#    when tandem observation files exist. No configuration required.
+#
+# Bell queue takes precedence: if a queued message exists, tandem is
+# deferred to the next hook invocation.
 #
 # Output format (when injecting):
 #   {
 #     "hookSpecificOutput": {
 #       "hookEventName": "PostToolUse",
-#       "additionalContext": "User feedback: <message>"
+#       "additionalContext": "<message>"
 #     }
 #   }
 #
-# Output when disabled or queue empty: (nothing - exit 0)
+# Output when nothing to inject: (nothing - exit 0)
 
 # Find project root (walk up to find .pennyfarthing)
 PROJECT_ROOT="$PWD"
@@ -31,76 +33,151 @@ while [[ "$PROJECT_ROOT" != "/" ]]; do
 done
 
 if [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]]; then
-  # No .pennyfarthing directory found - exit silently
   exit 0
 fi
 
 CONFIG_LOCAL_YAML="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
 BELL_QUEUE_FILE="$PROJECT_ROOT/.pennyfarthing/bell-queue.json"
 
-# Check if bell mode is enabled in config.local.yaml
-if [[ ! -f "$CONFIG_LOCAL_YAML" ]]; then
-  exit 0
+# Detect Cyclist — bell queue is a Cyclist-only feature
+IS_CYCLIST=false
+CYCLIST_PORT=""
+PORT_FILE="$PROJECT_ROOT/.cyclist-port"
+if [[ -f "$PORT_FILE" ]]; then
+  CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
+  if [[ -n "$CYCLIST_PORT" ]] && [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
+    IS_CYCLIST=true
+  fi
 fi
 
-# Parse YAML to check workflow.bell_mode - look for "bell_mode: true"
-# This handles both "bell_mode: true" and "  bell_mode: true" (indented under workflow)
-ENABLED=$(grep -E '^\s*bell_mode:\s*true' "$CONFIG_LOCAL_YAML" 2>/dev/null || true)
-if [[ -z "$ENABLED" ]]; then
-  exit 0
+# --- Bell queue check (Cyclist only, requires bell_mode: true) ---
+# Takes precedence over tandem injection when active.
+
+if [[ "$IS_CYCLIST" == "true" ]] && [[ -f "$CONFIG_LOCAL_YAML" ]]; then
+  BELL_ENABLED=$(grep -E '^\s*bell_mode:\s*true' "$CONFIG_LOCAL_YAML" 2>/dev/null || true)
+
+  if [[ -n "$BELL_ENABLED" ]] && [[ -f "$BELL_QUEUE_FILE" ]]; then
+    QUEUE_CONTENT=$(cat "$BELL_QUEUE_FILE" 2>/dev/null)
+    if [[ -n "$QUEUE_CONTENT" ]] && [[ "$QUEUE_CONTENT" != "[]" ]]; then
+      FIRST_MESSAGE_TEXT=$(echo "$QUEUE_CONTENT" | sed -n 's/.*"text"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+
+      if [[ -n "$FIRST_MESSAGE_TEXT" ]]; then
+        cat << EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
+  }
+}
+EOF
+
+        # Dequeue and notify Cyclist in background
+        (
+          if command -v jq &> /dev/null; then
+            jq 'if length > 0 then .[1:] else [] end' "$BELL_QUEUE_FILE" > "$BELL_QUEUE_FILE.tmp" 2>/dev/null && mv "$BELL_QUEUE_FILE.tmp" "$BELL_QUEUE_FILE"
+          fi
+
+          curl -s -X POST "http://localhost:$CYCLIST_PORT/api/bell-consumed" \
+            -H "Content-Type: application/json" \
+            -d "{\"text\": \"$FIRST_MESSAGE_TEXT\"}" \
+            >/dev/null 2>&1 || true
+        ) &
+
+        exit 0
+      fi
+    fi
+  fi
 fi
 
-# Check if queue file exists and has messages
-if [[ ! -f "$BELL_QUEUE_FILE" ]]; then
+# --- Tandem observation injection ---
+# Always active. No configuration required.
+# Checks .session/*-tandem-*.md files for new observations via mtime comparison.
+
+SESSION_DIR="$PROJECT_ROOT/.session"
+if [[ ! -d "$SESSION_DIR" ]]; then
   exit 0
 fi
 
-# Read queue and check if non-empty
-QUEUE_CONTENT=$(cat "$BELL_QUEUE_FILE" 2>/dev/null)
-if [[ -z "$QUEUE_CONTENT" ]] || [[ "$QUEUE_CONTENT" == "[]" ]]; then
+# Find tandem observation files
+TANDEM_FILES=$(find "$SESSION_DIR" -maxdepth 1 -name "*-tandem-*.md" 2>/dev/null)
+if [[ -z "$TANDEM_FILES" ]]; then
   exit 0
 fi
 
-# Extract first message text using simple parsing
-# The queue format is: [{"text":"...","images":[...]}, ...]
-FIRST_MESSAGE_TEXT=$(echo "$QUEUE_CONTENT" | sed -n 's/.*"text"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+# Check each tandem file for new content
+for TANDEM_FILE in $TANDEM_FILES; do
+  # Extract agent name from filename: *-tandem-{agent}.md
+  AGENT=$(echo "$TANDEM_FILE" | sed -n 's/.*-tandem-\([a-zA-Z_]*\)\.md$/\1/p')
+  if [[ -z "$AGENT" ]]; then
+    continue
+  fi
 
-if [[ -z "$FIRST_MESSAGE_TEXT" ]]; then
-  exit 0
-fi
+  # Get file mtime (portable: stat -f %m on macOS, stat -c %Y on Linux)
+  if [[ "$(uname)" == "Darwin" ]]; then
+    FILE_MTIME=$(stat -f %m "$TANDEM_FILE" 2>/dev/null)
+  else
+    FILE_MTIME=$(stat -c %Y "$TANDEM_FILE" 2>/dev/null)
+  fi
+  if [[ -z "$FILE_MTIME" ]]; then
+    continue
+  fi
 
-# Get Cyclist port (if running)
-CYCLIST_PORT=""
-PORT_FILE="$PROJECT_ROOT/.cyclist-port"
-if [[ -f "$PORT_FILE" ]]; then
-  CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
-fi
+  # Compare with saved mtime sidecar
+  MTIME_SIDECAR="$SESSION_DIR/.tandem-mtime-$AGENT"
+  SAVED_MTIME="0"
+  if [[ -f "$MTIME_SIDECAR" ]]; then
+    SAVED_MTIME=$(cat "$MTIME_SIDECAR" 2>/dev/null)
+  fi
+
+  if [[ "$FILE_MTIME" == "$SAVED_MTIME" ]]; then
+    continue
+  fi
+
+  # Read tandem file and extract latest observation
+  CONTENT=$(cat "$TANDEM_FILE" 2>/dev/null)
+  if [[ -z "$CONTENT" ]]; then
+    continue
+  fi
 
-# Output the hook response JSON
-cat << EOF
+  # Extract persona from header: **Observer:** agent (Persona Name)
+  PERSONA=$(echo "$CONTENT" | sed -n 's/.*\*\*Observer:\*\*[[:space:]]*[a-zA-Z_]*[[:space:]]*(\([^)]*\)).*/\1/p' | head -1)
+  if [[ -z "$PERSONA" ]]; then
+    PERSONA="Unknown"
+  fi
+
+  # Extract latest observation text (last ## [HH:MM] Observation block)
+  # Get text between last observation header and trailing ---
+  OBS_TEXT=$(echo "$CONTENT" | awk '
+    /^## \[[0-9]+:[0-9]+\] Observation/ { found=1; text=""; next }
+    found && /^---/ { next }
+    found && /^\*\*Trigger:\*\*/ { next }
+    found { text = text (text ? "\n" : "") $0 }
+    END { if (text) print text }
+  ' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+  if [[ -z "$OBS_TEXT" ]]; then
+    # Update mtime even if no parseable observation
+    echo "$FILE_MTIME" > "$MTIME_SIDECAR"
+    continue
+  fi
+
+  # Format as [Tandem] prefix and output
+  TANDEM_MSG="[Tandem] $PERSONA: $OBS_TEXT"
+
+  cat << EOF
 {
   "hookSpecificOutput": {
     "hookEventName": "PostToolUse",
-    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
+    "additionalContext": "$TANDEM_MSG"
   }
 }
 EOF
 
-# Remove the first message from the queue and notify Cyclist
-# Run in background to avoid blocking hook response
-(
-  # Dequeue using jq if available
-  if command -v jq &> /dev/null; then
-    jq 'if length > 0 then .[1:] else [] end' "$BELL_QUEUE_FILE" > "$BELL_QUEUE_FILE.tmp" 2>/dev/null && mv "$BELL_QUEUE_FILE.tmp" "$BELL_QUEUE_FILE"
-  fi
+  # Save mtime sidecar
+  echo "$FILE_MTIME" > "$MTIME_SIDECAR"
 
-  # Notify Cyclist browser to dequeue and display the message
-  if [[ -n "$CYCLIST_PORT" ]] && [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
-    curl -s -X POST "http://localhost:$CYCLIST_PORT/api/bell-consumed" \
-      -H "Content-Type: application/json" \
-      -d "{\"text\": \"$FIRST_MESSAGE_TEXT\"}" \
-      >/dev/null 2>&1 || true
-  fi
-) &
+  # Only inject one tandem observation per hook invocation
+  exit 0
+done
 
 exit 0