yoi/work-items/closed/20260531-043239-insomnia-pod-subcommand-runtime/item.md

id: 20260531-043239-insomnia-pod-subcommand-runtime slug: insomnia-pod-subcommand-runtime title: CLI: add insomnia pod runtime entrypoint status: closed kind: task priority: P2 labels: [cli, pod, nix] created_at: 2026-05-31T04:32:39Z updated_at: 2026-05-31T04:50:14Z assignee: null legacy_ticket: null

Background

Parent/umbrella ticket: single-binary-insomnia-cli.

The project currently has two installed command names:

• insomnia from the tui package for user-facing CLI/TUI/headless commands;
• insomnia-pod from the pod package for Pod runtime processes.

The target direction is one primary executable, insomnia, with insomnia pod ... as the Pod runtime entrypoint. Pod runtime remains a separate process when spawned; only the binary/entrypoint is unified.

This ticket is the first implementation step. It should add the new insomnia pod ... runtime entrypoint and share Pod runtime startup code, without yet requiring all internal spawn paths or packaging to drop insomnia-pod in the same diff.

Requirements

• Extract the current crates/pod/src/main.rs runtime startup into a library-callable entrypoint in the pod crate.
  • Keep existing Pod runtime flags/semantics.
  • Preserve INSOMNIA-READY stderr handshake and detached process behavior.
• Keep the existing insomnia-pod binary only as a temporary transition wrapper if needed for tests/current spawn defaults.
  • Do not present it as the long-term compatibility alias.
  • Do not change Nix installed command set in this ticket unless it is mechanically necessary.
• Add insomnia pod ... to the existing insomnia binary in the tui crate.
  • insomnia pod --help should reach the Pod runtime parser/help.
  • insomnia pod <runtime flags> should invoke the same library entrypoint as the old runtime path.
  • This means insomnia pod becomes reserved as a subcommand; a Pod literally named pod can still be addressed through explicit --pod pod if needed.
• Preserve existing user-facing TUI/CLI behavior for non-pod commands:
  • insomnia memory lint remains headless and returns before terminal/TUI/Pod side effects;
  • existing insomnia <pod-name> / --pod / --multi / resume behavior remains unchanged except for the reserved pod subcommand.
• Do not yet switch client::spawn_pod, SpawnPod, or RestorePod default command resolution to insomnia pod unless doing so is small and fully tested.
  • If not switched, create/fill a follow-up note for command resolution program + prefix_args migration.
• Do not rename the tui package/crate in this ticket.

Non-goals

• Removing insomnia-pod from packaging in this first step.
• Keeping insomnia-pod as a long-term alias.
• Merging Pod controller into the TUI process.
• Reworking Pod protocol or CLI UX beyond the new runtime subcommand.
• Feature-gating TUI dependencies.

Acceptance criteria

• insomnia pod --help works and uses the Pod runtime parser/help.
• insomnia-pod --help still works if the temporary binary remains.
• insomnia memory lint still runs headlessly without TUI/raw-terminal/Pod startup side effects.
• Existing TUI parser tests are updated for the reserved pod subcommand and preserve other positional Pod-name behavior.
• Pod runtime startup code has one shared library path rather than duplicated main logic.
• Follow-up work for switching internal spawn defaults and removing insomnia-pod packaging is recorded if not completed here.
• cargo fmt --check, focused cargo test for affected TUI/Pod CLI parsing, cargo check -p tui -p pod -p client, ./tickets.sh doctor, and git diff --check pass.