Launch Named Command Picker for Issue 258

Boundaries

flowchart LR
  JSON[Local agent JSON\ncommands array only] --> Identity[identity launch-command API]
  Identity --> CLI[tenex-edge launch\nTTY picker / command-name / override]
  Identity --> Registry[tmux registry\nnoninteractive default]
  CLI --> RPC[tmux_spawn RPC\nconcrete base_command argv]
  Registry --> RPC
  RPC --> Tmux[tmux session spawn]

Very High Level

Issue #258 should replace the singular agent launch `command` field with one canonical `commands` field. Use structured entries like `{"name": "read-only", "argv": ["claude"]}` and do not keep a legacy read fallback. If an existing agent file only has `command`, launch should treat it as having no configured commands and enter the missing-command flow. That avoids duplicate state and makes the schema contract unambiguous. Keep prompting out of the daemon. `tenex-edge launch <agent>` should resolve command choices before calling `tmux_spawn`: `-c/--command` remains a full argv override, a new noninteractive selector such as `--command-name <name>` selects one configured choice, and a TTY picker appears only when multiple choices exist and no selector was provided. The daemon RPC continues to receive a concrete `base_command`, preserving scripted and TUI spawn behavior. When no `commands` entries exist, the CLI should prompt from suggestions built from other local agent files first, then built-in harness defaults. Cross-agent adaptation should be conservative: support an explicit `{slug}` placeholder and only replace exact source-slug tokens or path filename stems, avoiding broad substring rewrites. Selecting or entering a command persists a named command atomically before spawn. Validation should cover strict schema parsing, multi-command precedence, no fallback from singular `command`, non-TTY errors, suggestion adaptation, CLI parsing, and the tmux resolver’s deterministic fallback. Update the launch and CLI docs after implementation; the planning PR itself is temporary and should be retired when the issue is completed.

Existing Rules Or ADRs

• No ADR files exist in this repository; governing constraints are AGENTS.md plus durable architecture/product docs.
• The GitHub issue remains the backlog source of truth; the generated docs/plans artifact is a temporary planning PR artifact and must be retired or collapsed after implementation.
• The implementation should respect the 300-line soft and 500-line hard file-size rule: identity.rs is already 382 lines, so launch-command parsing or suggestion logic should move into a cohesive submodule with narrow visibility.
• The product doctrine says agent identity persists across hosts; this plan keeps launch commands as local per-agent configuration attached to the existing local agent identity file, not to transient sessions.
• The daemon RPC stays noninteractive and receives concrete argv, preserving existing ownership boundaries between CLI UX, daemon provisioning, and tmux spawning.
• No compatibility layer is required for the old singular command field; strict replacement is an owner decision for this issue.

Rule Tension And Tightening

Possible loosening

• No permanent repository rule needs loosening.
• This intentionally accepts local config breakage for files that only use the old singular command field; that is a product/schema decision, not a repository-rule violation.

Possible tightening

• Consider documenting that daemon RPC handlers and background spawn paths must never prompt on stdin; all interactive selection belongs in explicit CLI/TUI layers.
• Consider documenting that local config schema replacements should avoid read fallbacks and aliases unless the owner explicitly asks for compatibility.

Alternatives Considered

• Keep legacy command as a read fallback: lower short-term friction, but rejected because the owner wants no legacy path and duplicate config state is not worth preserving.
• Array-of-tuples schema: compact, but weaker for validation and future fields than object entries with name and argv.
• Prompt inside resolve_spawn_entry or the daemon: fewer call sites, but unsafe for RPC, TUI, and background spawn callers because it can hang noninteractive paths.
• Always pick the first configured command silently: simplest, but fails the requested launch-time choice behavior and hides privileged command variants.
• Broad string substitution for cross-agent suggestions: convenient, but too likely to mutate unrelated paths or flags; explicit placeholders plus exact token/stem replacement is safer.