Feat/cursor runtime parity (#3522)

* feat(cursor): verify CLI preset, agent process disambiguation, beads handoff

- Cursor preset: cursor-agent + agent ProcessNames with tmux session env gate
- tmux: processNamesForSession drops ambiguous agent unless GT_AGENT=cursor
- config: CLI contract test, GT_AGENT_STUB_BIN_DIR, compact_report test fix
- docs/scripts: cursor-runtime beads task seed + handoff doc

Closes gastown-at8.1 (verify cursor-agent CLI).

* config: set Cursor ReadyDelayMs to 5000 for nudge poller

Cursor has HasTurnBoundaryDrain false; readiness uses delay + background
nudge poller. Align default delay with Copilot until a stable prompt
prefix exists.

Closes gastown-at8.2

Made-with: Cursor

* runtime: extend orphan/doctor/down filters for Cursor and Copilot

- TTY orphan/zombie detection: track cursor-agent, agent, copilot comm names
  alongside existing agents (internal/util/orphan.go).
- gt down town-root scan: allow the same comm names.
- doctor orphan-process check: match per-agent YOLO argv (claude/codex
  --dangerously-skip-permissions, cursor-agent -f, agent -f with Cursor
  tokens, copilot --yolo) instead of Claude-only flag.
- Add unit tests for gasTownRuntimeYOLO and argvHasFlag.

Closes gastown-at8.3

Made-with: Cursor

* web: detect cursor-agent and copilot in crew pane command

Extend pane #{pane_current_command} matching for dashboard crew state:
cursor-agent, copilot symlink/binary name, and bare "agent".

Closes gastown-at8.4

Made-with: Cursor

* cursor: add project skill for Gas Town + cursor-agent

Add .cursor/skills/gas-town-cursor with preset vs binary, hooks path, and
pointers to docs and AGENTS.md.

Closes gastown-at8.7

Made-with: Cursor

* cursor: add .cursor/README onboarding and beads doc links

Prerequisites, preset vs cursor-agent, hooks, test gate script reference,
manual smoke checklist, and link to docs/cursor-runtime-beads-tasks.md.

Closes gastown-at8.8
Closes gastown-at8.9

Made-with: Cursor

* config: dynamic built-in preset list in gt config help + otel GT_AGENT row

- Add config.BuiltInAgentPresetSummary() for sorted preset names.
- Populate gt config agent list/remove/default-agent long help and --provider
  flag text from the registry (includes cursor, copilot, opencode, …).
- Document GT_AGENT as preset names in otel architecture table.

Closes gastown-at8.5

Made-with: Cursor

* test: Cursor EnsureSettingsForRole, preset summary, and root-safe chmod tests

- Assert Cursor hooks land in workDir; TestBuiltInAgentPresetSummary for gt config help
- Skip chmod read-only installer/atomic tests when euid is root
- Tweak .cursor README and cursor-runtime-bd-tasks seed wording

Made-with: Cursor

Author: imkarrer

.cursor/README.md

@@ -0,0 +1,49 @@
+# Cursor / `cursor-agent` in this repo
+
+This directory holds **Cursor-specific** onboarding. For general Gas Town agent instructions, see [`../AGENTS.md`](../AGENTS.md) and [`../CLAUDE.md`](../CLAUDE.md).
+
+## Prerequisites
+
+1. **Build `gt`** from the repo root (`make build` or `go install ./cmd/gt`). Gas Town expects a working `gt` on your `PATH` for hooks and crew workflows.
+2. **`bd` (beads)** — issue DB under `.beads/`; see [`../CONTRIBUTING.md`](../CONTRIBUTING.md) for workflow.
+3. **Cursor Agent CLI** — install the `cursor-agent` binary per Cursor’s documentation. The Gas Town preset name is **`cursor`**; the process is typically **`cursor-agent`** (an **`agent`** symlink may exist).
+
+## Preset vs binary
+
+- **Preset:** `cursor` (`GT_AGENT=cursor`) — defined in `internal/config/agents.go`.
+- **CLI:** `cursor-agent` (args include **`-f`** for auto-approve in autonomous flows).
+
+## Hooks
+
+Hooks are installed under **`.cursor/hooks.json`** when roles are provisioned (`EnsureSettingsForRole`). After template or hook changes, restart agents (e.g. **`gt up --restore`**) so sessions pick up new files.
+
+## Skills
+
+See [`.cursor/skills/gas-town-cursor/SKILL.md`](skills/gas-town-cursor/SKILL.md) for agent-facing workflow (gt, resume, pointers to code).
+
+## Beads / plan tracking
+
+Epic tasks for Cursor runtime parity are tracked in beads; coordination notes and script:
+
+- [`docs/cursor-runtime-beads-tasks.md`](../docs/cursor-runtime-beads-tasks.md)
+- [`scripts/cursor-runtime-bd-tasks.sh`](../scripts/cursor-runtime-bd-tasks.sh)
+
+## Automated regression (local)
+
+CI already runs **`go test ./...`** (same coverage as a “gate” over these packages). For a **faster loop** while touching Cursor-related code, narrow packages:
+
+```bash
+go test ./internal/config/... ./internal/hooks/... ./internal/crew/... ./internal/tmux/... ./internal/runtime/... -count=1 -short
+```
+
+Run as a **non-root** user if you want chmod/read-only failure tests in `hooks` and `util` (root skips those cases by design).
+
+## Manual smoke (short)
+
+Run these only when changing behavior that tests do not cover end-to-end:
+
+1. `make build` — `gt` binary builds.
+2. `gt config agent list` — output includes the **`cursor`** preset.
+3. Start or attach to a dev session with **`GT_AGENT=cursor`** (or `--agent cursor`) and confirm the pane command shows **`cursor-agent`** or **`agent`** and the session receives hooks/nudges as expected.
+
+For full §9-style checklists, see the Cursor parity plan document in your planning folder if present; prefer adding **automated** tests in-repo when possible.

.cursor/skills/gas-town-cursor/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gas-town-cursor
+description: >
+  Develop and operate Gas Town with the Cursor agent preset (cursor-agent CLI):
+  gt flags, hooks at .cursor/hooks.json, session resume, and how this repo differs from README marketing copy.
+---
+
+# Gas Town + Cursor Agent CLI
+
+Use this skill when working **in this repository** with the **`cursor`** agent preset (CLI binary **`cursor-agent`**, sometimes symlinked as **`agent`**).
+
+## Concepts
+
+| Name | Meaning |
+|------|---------|
+| **Preset `cursor`** | Gas Town agent id (`GT_AGENT=cursor`). Config lives in `internal/config/agents.go` (`AgentCursor`). |
+| **Binary `cursor-agent`** | The Cursor Agent CLI process name for pane/detection; install docs may also symlink `agent` → same binary. |
+| **Hooks** | Cursor lifecycle hooks are configured at **`.cursor/hooks.json`** (see preset `HooksSettingsFile`). |
+
+## Essential commands
+
+- Build / run `gt` from repo root: `make build` or `go run ./cmd/gt …`.
+- Point a session at the Cursor preset: spawn or config so the runtime uses **`--agent cursor`** (or set **`GT_AGENT=cursor`** where applicable).
+- After changing hooks or settings: **`gt up --restore`** (or role-specific restart) so agents reload config.
+
+## Resume semantics
+
+The Cursor preset uses **`--resume <chatId>`** style resume (`ResumeStyle: flag`). Session identity is not carried in a dedicated env var in the same way as Claude’s `CLAUDE_SESSION_ID`; follow the preset fields in `internal/config/agents.go` (`ResumeFlag`, `ResumeStyle`).
+
+## Read more
+
+- Beads / plan handoff: [`docs/cursor-runtime-beads-tasks.md`](../../../docs/cursor-runtime-beads-tasks.md)
+- Agent instructions for automation: [`AGENTS.md`](../../../AGENTS.md) and [`CLAUDE.md`](../../../CLAUDE.md) (project-wide, not Cursor-only)
+
+## Boundary
+
+Project **README** is user-facing product overview; **`.cursor/README.md`** is Cursor-specific onboarding for this repo. Prefer linking to those files instead of duplicating long install steps inside skills.

docs/agent-provider-integration.md

@@ -529,7 +529,7 @@ Current agent capabilities at a glance:
 | Claude | Yes (settings.json) | `--resume` (flag) | Native | Yes | arg | node, claude |
 | Gemini | Yes | `--resume` (flag) | `-p` | No | arg | gemini |
 | Codex | No | `resume` (subcmd) | `exec` subcmd | No | none | codex |
-| Cursor | No | `--resume` (flag) | `-p` | No | arg | cursor-agent |
+| Cursor | Yes (`.cursor/hooks.json`) | `--resume` (flag) | `-p` / `--print` + `--output-format` | No | arg | cursor-agent, agent |
 | Auggie | No | `--resume` (flag) | No | No | arg | auggie |
 | AMP | No | `threads continue` (subcmd) | No | No | arg | amp |
 | OpenCode | Yes (plugin JS) | No | `run` subcmd | No | none | opencode, node, bun |

docs/cursor-runtime-beads-tasks.md

@@ -0,0 +1,21 @@
+# Cursor runtime plan — Beads tasks (handoff)
+
+These issues track **Cursor runtime parity**, **user-facing documentation clarity** (preset `cursor` vs CLI `cursor-agent` / `agent`), and **`.cursor/` onboarding**. Issue IDs vary by database.
+
+**Create issues (idempotent — skips if open `cursor-runtime`+`plan` issues exist):**
+
+```bash
+./scripts/cursor-runtime-bd-tasks.sh
+```
+
+**Full task scope:** see **§10a** and **§4b** in the Cursor parity plan (`cursor_runtime_parity_df5a36d7.plan.md` in your editor plans folder).
+
+**T5 (docs + CLI)** explicitly covers:
+
+- `gt config` / `internal/cmd/config.go` help — list **all** built-in presets, not only claude/gemini/codex.
+- **README** prerequisites — optional **Cursor Agent CLI** install; clarify **preset `cursor`** vs binaries.
+- **docs/INSTALLING.md**, **docs/reference.md** — same built-in lists as README; short note on **`cursor`** → `cursor-agent`.
+
+**Contributing:** [`CONTRIBUTING.md`](../CONTRIBUTING.md). Do not add `.beads/issues.jsonl` at repo root (CI). `bd vc commit` when persisting beads DB changes.
+
+**Migration:** If you seeded tasks with an older script, **retitle T5** in `bd` to match the table in the plan §10a, or close duplicates.

docs/design/otel/otel-architecture.md

@@ -410,7 +410,7 @@ run.id:uuid-1234
 | `GT_POLECAT` | `Toast`, `Shadow`, `Furiosa` | Polecat name (rig-specific) |
 | `GT_CREW` | `max`, `jane` | Crew member name |
 | `GT_SESSION` | `gt-gastown-Toast`, `hq-mayor` | Tmux session name |
-| `GT_AGENT` | `claudecode`, `codex`, `copilot` | Agent override (if specified) |
+| `GT_AGENT` | Preset names: `claude`, `gemini`, `codex`, `cursor`, `copilot`, `opencode`, … | Agent override (if specified) |
 | `GT_RUN` | UUID v4 | **PR #2199** — Run identifier, primary waterfall correlation key |
 | `GT_ROOT` | `/Users/pa/gt` | Town root path |
 | `CLAUDE_CONFIG_DIR` | `~/gt/.claude` | Runtime config directory (for agent overrides) |

internal/cmd/compact_report_test.go

@@ -28,12 +28,20 @@ func TestWispTypeToCategory(t *testing.T) {
 		t.Run(tc.wispType, func(t *testing.T) {
 			got := wispTypeToCategory(tc.wispType, "")
 			if got != tc.want {
-				t.Errorf("wispTypeToCategory(%q) = %q, want %q", tc.wispType, got, tc.want)
+				t.Errorf("wispTypeToCategory(%q, \"\") = %q, want %q", tc.wispType, got, tc.want)
 			}
 		})
 	}
 }
 
+func TestWispTypeToCategory_TitlePatrolFallback(t *testing.T) {
+	t.Parallel()
+	got := wispTypeToCategory("", "nightly patrol sweep")
+	if got != "Patrols" {
+		t.Errorf("empty wisp_type + patrol in title = %q, want Patrols", got)
+	}
+}
+
 func TestBuildReport(t *testing.T) {
 	result := &compactResult{
 		Deleted: []compactAction{

internal/cmd/config.go

@@ -42,15 +42,8 @@ Commands:
 var configAgentListCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List all agents",
-	Long: `List all available agents (built-in and custom).
-
-Shows all built-in agent presets (claude, gemini, codex) and any
-custom agents defined in your town settings.
-
-Examples:
-  gt config agent list           # Text output
-  gt config agent list --json    # JSON output`,
-	RunE: runConfigAgentList,
+	Long:  "", // Set in init() — includes full built-in preset list from config.BuiltInAgentPresetSummary()
+	RunE:  runConfigAgentList,
 }
 
 var configAgentGetCmd = &cobra.Command{
@@ -97,15 +90,9 @@ Examples:
 var configAgentRemoveCmd = &cobra.Command{
 	Use:   "remove <name>",
 	Short: "Remove custom agent",
-	Long: `Remove a custom agent definition from town settings.
-
-This removes a custom agent from your town settings. Built-in agents
-(claude, gemini, codex) cannot be removed.
-
-Examples:
-  gt config agent remove claude-glm`,
-	Args: cobra.ExactArgs(1),
-	RunE: runConfigAgentRemove,
+	Long:  "", // Set in init() — includes full built-in preset list
+	Args:  cobra.ExactArgs(1),
+	RunE:  runConfigAgentRemove,
 }
 
 // Cost-tier subcommand
@@ -192,24 +179,8 @@ func runConfigCostTier(cmd *cobra.Command, args []string) error {
 var configDefaultAgentCmd = &cobra.Command{
 	Use:   "default-agent [name]",
 	Short: "Get or set default agent",
-	Long: `Get or set the default agent for the town.
-
-With no arguments, shows the current default agent.
-With an argument, sets the default agent to the specified name.
-
-The default agent is used when a rig doesn't specify its own agent
-setting. Can be a built-in preset (claude, gemini, codex) or a
-custom agent name.
-
-Use 'gt config default-agent list' to see all available agents.
-
-Examples:
-  gt config default-agent           # Show current default
-  gt config default-agent list      # List available agents
-  gt config default-agent claude    # Set to claude
-  gt config default-agent gemini    # Set to gemini
-  gt config default-agent my-custom # Set to custom agent`,
-	RunE: runConfigDefaultAgent,
+	Long:  "", // Set in init() — includes full built-in preset list
+	RunE:  runConfigDefaultAgent,
 }
 
 var configDefaultAgentListCmd = &cobra.Command{
@@ -1255,10 +1226,47 @@ func parseBool(s string) (bool, error) {
 }
 
 func init() {
+	presets := config.BuiltInAgentPresetSummary()
+
+	configAgentListCmd.Long = fmt.Sprintf(`List all available agents (built-in and custom).
+
+Shows all built-in agent presets (%s) and any
+custom agents defined in your town settings.
+
+Examples:
+  gt config agent list           # Text output
+  gt config agent list --json    # JSON output`, presets)
+
+	configAgentRemoveCmd.Long = fmt.Sprintf(`Remove a custom agent definition from town settings.
+
+This removes a custom agent from your town settings. Built-in agents
+(%s) cannot be removed.
+
+Examples:
+  gt config agent remove claude-glm`, presets)
+
+	configDefaultAgentCmd.Long = fmt.Sprintf(`Get or set the default agent for the town.
+
+With no arguments, shows the current default agent.
+With an argument, sets the default agent to the specified name.
+
+The default agent is used when a rig doesn't specify its own agent
+setting. Can be a built-in preset (%s) or a
+custom agent name.
+
+Use 'gt config default-agent list' to see all available agents.
+
+Examples:
+  gt config default-agent           # Show current default
+  gt config default-agent list      # List available agents
+  gt config default-agent claude    # Set to claude
+  gt config default-agent gemini    # Set to gemini
+  gt config default-agent my-custom # Set to custom agent`, presets)
+
 	// Add flags
 	configAgentListCmd.Flags().BoolVar(&configAgentListJSON, "json", false, "Output as JSON")
 	configDefaultAgentListCmd.Flags().BoolVar(&configDefaultAgentListJSON, "json", false, "Output as JSON")
-	configAgentSetCmd.Flags().StringVar(&configAgentSetProvider, "provider", "", "Agent provider preset (e.g. claude, gemini, codex); inferred from command name if not set")
+	configAgentSetCmd.Flags().StringVar(&configAgentSetProvider, "provider", "", fmt.Sprintf("Agent provider preset (e.g. %s); inferred from command name if not set", presets))
 
 	// Add agent subcommands
 	configAgentCmd := &cobra.Command{

internal/cmd/down.go

@@ -742,8 +742,8 @@ func verifyShutdown(t *tmux.Tmux, townRoot string) []string {
 	return respawned
 }
 
-// findOrphanedClaudeProcesses finds Claude/node processes that are running in the
-// town directory but aren't associated with any active tmux session.
+// findOrphanedClaudeProcesses finds Gas Town agent processes (claude/codex/opencode/cursor-agent/copilot/node)
+// that are running in the town directory but aren't associated with any active tmux session.
 // This can happen when tmux sessions are killed but child processes don't terminate.
 //
 // Only matches processes whose full command line references the town root path,
@@ -778,7 +778,7 @@ func findOrphanedClaudeProcesses(townRoot string) []int {
 		// Only consider known Gas Town process names
 		comm := strings.ToLower(fields[1])
 		switch comm {
-		case "claude", "claude-code", "codex", "node":
+		case "claude", "claude-code", "codex", "opencode", "cursor-agent", "agent", "copilot", "node":
 			// Potential Gas Town process
 		default:
 			continue
@@ -1205,4 +1205,3 @@ func containsPathBoundary(line, path string) bool {
 	}
 	return false
 }
-

internal/config/agents.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"sync"
 )
@@ -61,7 +62,7 @@ type AgentPresetInfo struct {
 
 	// ProcessNames are the process names to look for when detecting if the agent is running.
 	// Used by tmux.IsAgentRunning to check pane_current_command.
-	// E.g., ["node"] for Claude, ["cursor-agent"] for Cursor.
+	// E.g., ["node"] for Claude, ["cursor-agent", "agent"] for Cursor (install script symlinks both names).
 	ProcessNames []string `json:"process_names,omitempty"`
 
 	// SessionIDEnv is the environment variable for session ID.
@@ -285,15 +286,18 @@ var builtinPresets = map[AgentPreset]*AgentPresetInfo{
 		InstructionsFile:  "AGENTS.md",
 	},
 	AgentCursor: {
-		Name:                AgentCursor,
-		Command:             "cursor-agent",
-		Args:                []string{"-f"}, // Force mode (YOLO equivalent), -p requires prompt
-		ProcessNames:        []string{"cursor-agent"},
+		Name:    AgentCursor,
+		Command: "cursor-agent",
+		// -f/--force: auto-approve tool use (see cursor-agent --help). Install script also symlinks "agent" -> same binary.
+		Args: []string{"-f"},
+		// cursor-agent + agent (install symlinks). Pane matching for "agent" requires session env (GT_AGENT=cursor or GT_PROCESS_NAMES includes cursor-agent); see internal/tmux processNamesForSession.
+		ProcessNames:        []string{"cursor-agent", "agent"},
 		SessionIDEnv:        "", // Uses --resume with chatId directly
 		ResumeFlag:          "--resume",
 		ResumeStyle:         "flag",
 		SupportsHooks:       true,
 		SupportsForkSession: false,
+		// Non-interactive/headless: -p/--print + --output-format json (matches cursor-agent --help).
 		NonInteractive: &NonInteractiveConfig{
 			PromptFlag: "-p",
 			OutputFlag: "--output-format json",
@@ -303,8 +307,10 @@ var builtinPresets = map[AgentPreset]*AgentPresetInfo{
 		ConfigDir:         ".cursor",
 		HooksProvider:     "cursor",
 		HooksDir:          ".cursor",
-		HooksSettingsFile: "hooks.json",
+		HooksSettingsFile: "hooks.json", // installed path: .cursor/hooks.json
 		InstructionsFile:  "AGENTS.md",
+		// No stable ReadyPromptPrefix yet; delay before nudge poller / early input (HasTurnBoundaryDrain is false — see Copilot).
+		ReadyDelayMs: 5000,
 	},
 	AgentAuggie: {
 		Name:                AgentAuggie,
@@ -582,6 +588,14 @@ func ListAgentPresets() []string {
 	return names
 }
 
+// BuiltInAgentPresetSummary returns a sorted, comma-separated list of built-in preset names
+// for CLI help text (gt config agent list, default-agent, --provider, etc.).
+func BuiltInAgentPresetSummary() string {
+	names := ListAgentPresets()
+	sort.Strings(names)
+	return strings.Join(names, ", ")
+}
+
 // DefaultAgentPreset returns the default agent preset (Claude).
 func DefaultAgentPreset() AgentPreset {
 	return AgentClaude