devctl CLI: native terminal attach and shell completion

Attach to a session's terminal: `devctl remote-terminal`

devctl remote-terminal <session> (alias devctl attach-native) puts your terminal straight into the session's tmux inside its container. The usual devctl session attach goes through the Core terminal relay; this command runs the tmux client yourself, with docker exec, over SSH when the Host is remote:

# Remote Host (the Host ID is its SSH alias)
ssh -t build-host 'docker exec -it -u 20123:19999 devctl-example-main tmux -S /var/lib/devctl/session/homes/<id>/tmux/tmux-20123/default attach -t <id>'
# Local Docker Desktop Host
docker exec -it -u 20123:19999 devctl-example-main tmux -S /var/lib/devctl/session/homes/<id>/tmux/tmux-20123/default attach -t <id>

<session> can be a session ID, a session name or display name, or project/name. A name that matches more than one session is refused, and the error lists the project/name (id) forms to use instead.

Option Effect
(none) Check that the Host is reachable, then run the command so you land in the terminal
--print Print the command instead of running it
--read-only Attach with tmux attach -r
--json Print the structured target: Host, connection, container, UID, GID, socket, tmux target
--ssh TARGET Reach the Host through another SSH alias or user@address instead of its Host ID
--local Run docker exec on this machine (use this when the Host is this machine's Docker)
--list List the sessions you can attach to (project/name, status, ID)

Detach with the session's tmux detach key: Ctrl+] in managed sessions, or Ctrl+b d.

Where the target comes from

Nothing in the command is guessed by the CLI:

  1. Core resolves the reference among the sessions you can reach. The command is issued only to the session's owner, the canonical operator, or a user with a control share. A view share gets a read-only attach (-r). Everyone else gets "Session not found".
  2. Core asks the session's Host for the location. The Host takes the session's HOME from its authoritative runtime key: the session UUID for new sessions, and the original name for legacy ones. It then looks inside the running container for the tmux socket under that HOME that answers for the exact tmux session. It returns the socket only when exactly one socket answers and the socket's owner is the UID the session's process runs as. Task-container (Control Room pool) sessions have their own per-slot UID; the Host reports it the same way. The docker exec user is that UID with the shared session group (19999).
  3. Every request is recorded in the audit log as session.terminal-command, both issued and refused ones, with the access level and mode.

The command still needs your own SSH access to the Host, and permission to run docker there, or a local Docker Desktop for the local-docker Host. Core's check decides who receives the command and puts it on the audit record. It is not a sandbox: anyone who can already run docker exec on a Host can reach every container there. --read-only and view shares therefore only make the tmux client read-only.

Errors and next steps

Message Next step
Session … is exited; start it first devctl session resume-id <id>, or thaw a frozen session
not reachable over SSH as "<alias>" Make ssh <alias> work without a password prompt (add a Host <alias> entry to ~/.ssh/config), or pass --ssh
Docker there cannot see the … container Check that the SSH user can run docker ps on the Host, and that the session is still running
Local Docker cannot see … Start Docker Desktop, or pass --ssh <alias> if the Host is remote
cannot report session terminals yet Upgrade the Host agent: devctl install-host <alias> --upgrade
tmux server is not running The container runs but the session's tmux is gone: resume the session
This session runs directly on its Host Host-mode sessions have no container; use devctl session attach-id <id>

The reachability check is ssh -o BatchMode=yes -o ConnectTimeout=8 <host> docker inspect …. Run it yourself with --print if you need to debug the connection.

MCP

get_session_terminal_command is an entry of the shared operation registry (packages/contracts/src/operation-tool-definitions.ts), so the operator MCP server and Control Room sessions get the same typed tool, paired with devctl remote-terminal. It takes session and an optional readOnly, and calls POST /v1/session-terminal-command with the same authorization and audit as the CLI. The structured result has sessionId, hostId, connection, sshTarget, container (containerId, containerName, uid, gid, socket, target, taskSlot), access, readOnly, and the default command and argv. The tool never runs the command. --ssh and --local are CLI-only, because they depend on the operator's own machine. When a Host ID is not a usable SSH alias, sshTarget is null and command is the docker exec part to run on that Host.

Shell completion: `devctl completion bash|zsh|fish`

devctl completion <shell> prints a completion script. The command tree (commands, subcommands, aliases and flags) is generated from the CLI's command registry (apps/cli/src/command-registry.ts) together with the commands derived from the shared operation registry under the roots that the devctl wrapper routes. A test fails when the registry misses a command that the CLI or the devctl wrapper dispatches. While you type, the script calls the hidden devctl __complete <words…> for live values: sessions (project/name; IDs once you type an ID prefix), Projects, Hosts (after --ssh and --host) and accounts. That call:

When Core or the stack is unreachable, __complete returns only static values, or nothing at all. The script then falls back to the static tree embedded in it.

zsh (macOS)

The installer does not change shell startup files, so add completion yourself:

mkdir -p ~/.zsh/completions
devctl completion zsh > ~/.zsh/completions/_devctl

In ~/.zshrc, before any existing compinit line:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Open a new shell, or run exec zsh. If you call devctl from the checkout as ./devctl, zsh matches the completion by the command's base name. You can also put the checkout's devctl on your PATH (for example ln -s "$PWD/devctl" /usr/local/bin/devctl).

bash

mkdir -p ~/.local/share/bash-completion/completions
devctl completion bash > ~/.local/share/bash-completion/completions/devctl
# or, in ~/.bashrc:
source <(devctl completion bash)

fish

devctl completion fish > ~/.config/fish/completions/devctl.fish

Regenerate the script after upgrading devctl, so that new commands appear.