Merge PR #2589: fix: FormatMailBody detects run.sh and dispatches script instead of markdown

Dogs now receive concrete 'bash run.sh' commands instead of ambiguous markdown instructions when a plugin has a run.sh. Prevents dogs from improvising bash that kills valid sessions.

PR: #2589
Author: seanbearden

Author: steveyegge

internal/plugin/scanner.go

@@ -130,7 +130,18 @@ func (s *Scanner) loadPlugin(pluginDir string, location Location, rigName string
 		return nil, fmt.Errorf("reading plugin.md: %w", err)
 	}
 
-	return parsePluginMD(content, pluginDir, location, rigName)
+	plugin, err := parsePluginMD(content, pluginDir, location, rigName)
+	if err != nil {
+		return nil, err
+	}
+
+	// Check for run.sh alongside plugin.md
+	runScriptPath := filepath.Join(pluginDir, "run.sh")
+	if info, statErr := os.Stat(runScriptPath); statErr == nil && !info.IsDir() {
+		plugin.HasRunScript = true
+	}
+
+	return plugin, nil
 }
 
 // parsePluginMD parses a plugin.md file with TOML frontmatter.

internal/plugin/scanner_test.go

@@ -3,6 +3,7 @@ package plugin
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -400,17 +401,60 @@ func TestParsePluginMD_GitHubSheriff(t *testing.T) {
 }
 
 func TestParsePluginMD_SessionHygiene(t *testing.T) {
-	// Verify the actual session-hygiene plugin.md parses correctly.
-	content, err := os.ReadFile(filepath.Join("..", "..", "plugins", "session-hygiene", "plugin.md"))
+	// Use a temp dir with a fixture plugin.md and run.sh so the test
+	// doesn't depend on the local filesystem layout (fails in CI).
+	pluginDir := t.TempDir()
+
+	pluginContent := []byte(`+++
+name = "session-hygiene"
+description = "Clean up zombie tmux sessions and orphaned dog sessions"
+version = 2
+
+[gate]
+type = "cooldown"
+duration = "30m"
+
+[tracking]
+labels = ["plugin:session-hygiene", "category:cleanup"]
+digest = true
+
+[execution]
+timeout = "5m"
+notify_on_failure = true
+severity = "low"
++++
+
+# Session Hygiene
+
+Deterministic cleanup of zombie tmux sessions and orphaned dog sessions.
+`)
+
+	if err := os.WriteFile(filepath.Join(pluginDir, "plugin.md"), pluginContent, 0644); err != nil {
+		t.Fatalf("writing plugin.md fixture: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(pluginDir, "run.sh"), []byte("#!/bin/bash\necho ok\n"), 0755); err != nil {
+		t.Fatalf("writing run.sh fixture: %v", err)
+	}
+
+	content, err := os.ReadFile(filepath.Join(pluginDir, "plugin.md"))
 	if err != nil {
-		t.Skipf("session-hygiene plugin not found (expected in plugins/): %v", err)
+		t.Fatalf("reading plugin.md fixture: %v", err)
 	}
 
-	plugin, err := parsePluginMD(content, "/test/session-hygiene", LocationRig, "gastown")
+	plugin, err := parsePluginMD(content, pluginDir, LocationRig, "gastown")
 	if err != nil {
 		t.Fatalf("parsePluginMD failed: %v", err)
 	}
 
+	// Verify run.sh detection (loadPlugin does this, not parsePluginMD)
+	runScriptPath := filepath.Join(pluginDir, "run.sh")
+	if info, statErr := os.Stat(runScriptPath); statErr == nil && !info.IsDir() {
+		plugin.HasRunScript = true
+	}
+	if !plugin.HasRunScript {
+		t.Error("expected HasRunScript=true for session-hygiene (has run.sh)")
+	}
+
 	if plugin.Name != "session-hygiene" {
 		t.Errorf("expected name 'session-hygiene', got %q", plugin.Name)
 	}
@@ -509,3 +553,123 @@ version = 1
 		t.Errorf("expected location 'rig', got %q", plugins[0].Location)
 	}
 }
+
+func TestLoadPlugin_DetectsRunScript(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "plugin-runsh-test")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	// Create plugin dir with plugin.md AND run.sh
+	pluginDir := filepath.Join(tmpDir, "plugins", "with-script")
+	if err := os.MkdirAll(pluginDir, 0755); err != nil {
+		t.Fatalf("failed to create plugin dir: %v", err)
+	}
+	pluginContent := []byte(`+++
+name = "with-script"
+description = "Plugin with run.sh"
+version = 1
++++
+
+# Instructions (should be ignored when run.sh exists)
+`)
+	if err := os.WriteFile(filepath.Join(pluginDir, "plugin.md"), pluginContent, 0644); err != nil {
+		t.Fatalf("failed to write plugin.md: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(pluginDir, "run.sh"), []byte("#!/bin/bash\necho hello\n"), 0755); err != nil {
+		t.Fatalf("failed to write run.sh: %v", err)
+	}
+
+	// Create plugin dir with plugin.md only (no run.sh)
+	pluginDirNoScript := filepath.Join(tmpDir, "plugins", "no-script")
+	if err := os.MkdirAll(pluginDirNoScript, 0755); err != nil {
+		t.Fatalf("failed to create plugin dir: %v", err)
+	}
+	noScriptContent := []byte(`+++
+name = "no-script"
+description = "Plugin without run.sh"
+version = 1
++++
+
+# Instructions
+`)
+	if err := os.WriteFile(filepath.Join(pluginDirNoScript, "plugin.md"), noScriptContent, 0644); err != nil {
+		t.Fatalf("failed to write plugin.md: %v", err)
+	}
+
+	scanner := NewScanner(tmpDir, nil)
+	plugins, err := scanner.DiscoverAll()
+	if err != nil {
+		t.Fatalf("DiscoverAll failed: %v", err)
+	}
+
+	if len(plugins) != 2 {
+		t.Fatalf("expected 2 plugins, got %d", len(plugins))
+	}
+
+	byName := make(map[string]*Plugin)
+	for _, p := range plugins {
+		byName[p.Name] = p
+	}
+
+	if p, ok := byName["with-script"]; !ok {
+		t.Fatal("expected to find 'with-script' plugin")
+	} else if !p.HasRunScript {
+		t.Error("expected HasRunScript=true for plugin with run.sh")
+	}
+
+	if p, ok := byName["no-script"]; !ok {
+		t.Fatal("expected to find 'no-script' plugin")
+	} else if p.HasRunScript {
+		t.Error("expected HasRunScript=false for plugin without run.sh")
+	}
+}
+
+func TestFormatMailBody_WithRunScript(t *testing.T) {
+	p := &Plugin{
+		Name:         "test-plugin",
+		Description:  "A test plugin",
+		Path:         "/home/user/gt/plugins/test-plugin",
+		HasRunScript: true,
+	}
+
+	body := p.FormatMailBody()
+
+	// Must contain the bash command to run the script
+	if !strings.Contains(body, "cd /home/user/gt/plugins/test-plugin && bash run.sh") {
+		t.Error("expected mail body to contain run.sh execution command")
+	}
+	// Must instruct dog NOT to interpret markdown
+	if !strings.Contains(body, "Do NOT interpret the plugin.md instructions") {
+		t.Error("expected mail body to warn against interpreting markdown")
+	}
+	// Must NOT contain "## Instructions" section
+	if strings.Contains(body, "## Instructions") {
+		t.Error("expected mail body to NOT contain markdown instructions section")
+	}
+}
+
+func TestFormatMailBody_WithoutRunScript(t *testing.T) {
+	p := &Plugin{
+		Name:         "test-plugin",
+		Description:  "A test plugin",
+		Path:         "/home/user/gt/plugins/test-plugin",
+		Instructions: "Do the thing.",
+		HasRunScript: false,
+	}
+
+	body := p.FormatMailBody()
+
+	// Must contain the instructions section
+	if !strings.Contains(body, "## Instructions") {
+		t.Error("expected mail body to contain instructions section")
+	}
+	if !strings.Contains(body, "Do the thing.") {
+		t.Error("expected mail body to contain plugin instructions")
+	}
+	// Must NOT contain run.sh dispatch
+	if strings.Contains(body, "bash run.sh") {
+		t.Error("expected mail body to NOT contain run.sh command")
+	}
+}

internal/plugin/types.go

@@ -44,6 +44,11 @@ type Plugin struct {
 
 	// Instructions is the markdown body (after frontmatter).
 	Instructions string `json:"instructions,omitempty"`
+
+	// HasRunScript is true when a run.sh exists alongside plugin.md.
+	// When true, FormatMailBody instructs the dog to execute the script
+	// instead of interpreting the markdown instructions.
+	HasRunScript bool `json:"has_run_script,omitempty"`
 }
 
 // Location indicates where a plugin was discovered.
@@ -159,6 +164,20 @@ func (p *Plugin) Summary() PluginSummary {
 // This is the canonical formatting used by both the daemon dispatcher
 // and the gt dog dispatch command.
 func (p *Plugin) FormatMailBody() string {
+	if p.HasRunScript {
+		return fmt.Sprintf(
+			"Execute the following plugin script:\n\n"+
+				"**Plugin**: %s\n"+
+				"**Description**: %s\n\n"+
+				"```bash\ncd %s && bash run.sh\n```\n\n"+
+				"Run this command EXACTLY. Do NOT interpret the plugin.md instructions.\n"+
+				"Do NOT write your own implementation. Just run the script and report the output.\n\n"+
+				"After completion:\n"+
+				"1. Create a wisp to record the result (success/failure)\n"+
+				"2. Run `gt dog done` — this clears your work and auto-terminates the session\n",
+			p.Name, p.Description, p.Path)
+	}
+
 	var sb strings.Builder
 
 	sb.WriteString("Execute the following plugin:\n\n")