How should AgentDeck preserve remote sessions, weights, and custom launch arguments?

[puritysb]

Why this discussion exists

AgentDeck is moving toward a daemon-first architecture: install the daemon once, then run Claude Code, Codex, or OpenCode normally while lifecycle hooks and agent-native events provide the authoritative session state.

We had planned to deprecate and eventually remove the older agentdeck <agent> managed PTY path. Feedback from @doug-w on #273, who implemented and actively uses remote attach and session weights, exposed an important product distinction:

The PTY implementation may be legacy, but several workflows available through it are not.

Treating those workflows as incidental implementation details would make the architecture cleaner by making the product materially less useful. That is not an acceptable migration.

Current guarantee

• AgentDeck npm 1.2.0 does not remove agentdeck claude, agentdeck codex, agentdeck opencode, or agentdeck monitor.
• --remote-daemon, --weight, AGENTDECK_CLAUDE_ARGS, the corresponding agent argument variables, and the existing managed-session controls continue to work.
• No removal date is set.
• The daemon-first path remains the recommended default for ordinary local sessions.
• The managed implementation will not be removed until active workflows have validated replacements or an explicit long-term compatibility decision.

Capabilities we need to preserve

Capability	Why it matters	Candidate daemon-first direction
Cross-machine --remote-daemon attach and same-socket reverse control	One main-node daemon and deck can observe and control workers that are reachable only outbound, including SSH/NAT topologies	An outbound worker/relay owned by the daemon architecture, without requiring AgentDeck to own the agent PTY
--weight session ordering	Users can make physical deck slots mirror Windows Terminal or iTerm tab order instead of relying on incidental discovery order	Daemon-persisted session pin/order metadata that also works for normally launched, observed sessions
AGENTDECK_CLAUDE_ARGS and related custom launch arguments	Stable per-user agent arguments can be composed with one-off commands without retyping or replacing resume commands	A lightweight non-PTY launch/exec path, agent-native configuration where equivalent, or another explicit argument-profile mechanism
Terminal-specific steering and telemetry	Some real mode, option, cursor, interrupt, and status-line behavior is not exposed by hooks	Preserve only the proven gaps that hooks/agent APIs cannot cover; do not make terminal parsing a lifecycle authority again

These are design directions, not decisions already made. The goal is to preserve the user outcome while allowing the managed PTY internals and per-session mini-daemon to shrink or disappear over time.

Please share your workflow

If you use agentdeck claude, agentdeck codex, agentdeck opencode, or agentdeck monitor, please include as much of the following as you can:

1. OS, terminal, and the representative command or shell configuration.
2. Remote topology: main node, worker machines, LAN/VPN/SSH path, and which controls you use remotely.
3. How you assign weights and whether they should persist across process or machine restarts.
4. Which AGENTDECK_*_ARGS values you use and why agent-native configuration is or is not sufficient.
5. Which terminal UI observations or controls cannot be replaced by current hook/event behavior.
6. What a migration must preserve for you to adopt it without maintaining a fork.

Please redact tokens, hostnames, session IDs, and other private values.

How this relates to #273

#273 remains the implementation and release tracker. This Discussion is the place to collect real workflows, compare replacement designs, and record compatibility requirements. Decisions made here will be reflected back into #273 as explicit implementation gates and regression tests.