ls-wf-sudo-tmux-session

Use this workflow package for server or remote ops through tmux wrappers. Primary source references: ls/docs/ops/tmux-ops-managed.md and ls/docs/ops/tmux-ops-remote.md. Installed packages expose the same references through the localsetup://doc/ops/tmux-ops-managed.md and localsetup://doc/ops/tmux-ops-remote.md aliases.

Load this workflow automatically before any command or retry that requests sudo, root/admin access, elevation, require_escalated, or a pseudo-terminal for privileged work. Treat a transcribed request for “pseudo” as a sudo trigger when the command needs privilege. Do not wait for a reminder, switch to direct SSH or raw tmux commands, or run an unprivileged-looking retry that still invokes sudo.

When to use

Use this workflow when a command needs sudo, root/admin elevation, require_escalated, pseudo-terminal/PTY behavior, interactive sudo or elevated terminal password prompt handoff, or durable managed tmux run tracking through ls/tools/tmux_ops. Installed packages expose that tool through the localsetup://tool/tmux_ops alias.

Do not use this workflow for normal repo-local coding, API authentication, token setup, non-privileged file edits, or commands that can run safely without managed terminal state.

Execution authorization boundary

Terminal and credential readiness do not authorize a command. Reuse the current user-approved task scope and its exact target/effect checks. Routine necessary work does not need another approval merely because sudo is required. Destructive work retains the owning recovery plan and explicit scope approval. Never expand command authority from a credential variable, a successful probe or a pane name.

Managed pane sequence

1. Resolve the actual caller, canonical repository, exact target and live owner. Use the existing private task state root. Normal pick requires verified tmux caller context and does not create a separate operations session or tab.
2. Run ./ls/tools/tmux_ops pick, supplying --repository, --host-alias, --cwd or --state-dir only when needed to bind the selected context. Retain the returned exact target, parent and ownership handles.
3. Reuse the controller-owned child directly below that parent. The root name is <repo>-sudo; an admitted host uses <repo>-<exact-alias>-sudo. Different controllers may have identical names. Ownership and native IDs distinguish them. The child occupies one third of the parent's original height without changing focus.
4. Run exact argv with ./ls/tools/tmux_ops run -t <target> -- <argv...>. The managed Bash handler checks its primary prompt, empty Readline buffer, machine/TTY/shell generation and writer lease before executing a staged request. The adapter sends only the reserved trigger, never command text and Enter. Partial input, continuation prompts and unsupported shells stop input.
5. Direct privileged argv automatically uses the shared operation-bound sudo owner. It checks sudo availability and resolves only GENERIC_SUDO_KEY from the controller environment, then EnvMan when that variable is absent. An explicit empty or invalid environment value is authoritative. Values travel only as private transient input through the framed channel. Workload children do not inherit any *_SUDO_KEY variables.
6. Authentication and the exact authorized command share one sudo -A invocation; command stdin is preserved. Cached validation is an observation, never a guarantee for a separate invocation. Authentication has its own configurable budget, defaulting to 120 seconds with run --auth-timeout <secs>. Unknown prompts, owner loss or attempt exhaustion stop credential delivery without interrupting an already-running workload.
7. Track the returned operation/run ID through status. A slow workload stays running after its observation timeout. Preserve its status_handle and use status --status-handle <handle> --wait --timeout <secs> to read the durable receipt, including after a directory change or controller restart. A completion receipt proves completion; dispatch acknowledgement does not. busy receives no new command, and unknown permits read-only reconciliation only. Never switch backends or repeat an uncertain request.

Herdr and tmux use the shared LocalSetup terminal core. FleetOps owns its exact host admission, authority and receipts. Select a qualified SSH/tmux fallback before dispatch when a Herdr endpoint is unavailable. A wrong-machine attachment may detach or log out automatically only when its recorded ownership and idle state are proven; verify the original local shell before changing directory or connecting elsewhere.

Missing credentials, EnvMan load errors, expired authentication, unsupported authentication, policy denial and uncertain outcomes have distinct safe diagnostics. Use a manual fallback only when a run result explicitly says action_required and includes sudo.manual_fallback; that receipt proves the workload did not start. Run that exact quoted command once in the qualified pane. For timeout, owner loss, policy denial, running, or unknown, use read-only status reconciliation only; never replay. Do not run a separate sudo -v, type a password into command text, print it, write it to a file or treat sudo ready as an execution grant.

./ls/tools/tmux_ops capabilities reports the local API. A probe reports stale or incompatible remote helper versions separately from sudo policy or credential failures.

The old standalone ops* session workflow is explicit compatibility only: pick --legacy-session and run --legacy-session -t <session>. It is not the normal automatic path. Do not infer legacy lifecycle from a binary override.

Legacy sudo keepalive

For active privileged work where the user has already entered sudo in the same managed pane, use bounded one-shot keepalive commands instead of ad hoc loops.

1. Request a marker only after probe reports sudo ready:

   ./ls/tools/tmux_ops keepalive request -t <session> --owner <id> --ttl-seconds 7200 --max-refreshes 24 --reason "<reason>"
   

2. Refresh only as an explicit one-shot action while privileged work remains active and the managed pane is idle between commands:

   ./ls/tools/tmux_ops keepalive refresh -t <session>
   

3. Report state with ./ls/tools/tmux_ops keepalive status -t <session>.

4. Clear the marker with ./ls/tools/tmux_ops keepalive clear -t <session> --owner <id> when privileged work ends.

Keepalive is restricted to managed ops* sessions, caps TTL at 7200 seconds and refreshes at 24, and runs only hard-coded sudo -n -v during refresh. Its request path performs noninteractive checks only and never starts environment-key or password authentication. It must not start a background loop, prompt for a password, or refresh while a managed run is active, another refresh is in progress, or the pane is not idle.

Load the full procedure from ls-wf-sudo-tmux-session and ls-wf-tmux-terminal-mode before privileged commands. Environment credential presence, a successful probe, an attached operator, sudo ready, or cached sudo state confirms transport readiness only; it never authorizes a command.