feat(tmux): self-registering tmux hooks via managed block

[rtalexk]

Context

demux's tmux integration (done-state clearing, the sticky sidebar follow/slot
hooks) is delivered through tmux hooks. Until now those hooks were installed by
hand: demux hooks init --tool tmux printed a multi-line snippet the user
pasted into ~/.tmux.conf and re-sourced.

That snippet is a maintenance trap. Every time demux's hook set changes — a new
event, a corrected flag, an added run-shell -b — the pasted copy goes stale.
A stale snippet silently misbehaves (wrong flags expand to empty values) or
stacks duplicate hooks on re-source, and nothing tells the user to re-paste.
The hook set and the user's config drift apart with no feedback loop.

This PR closes that gap: the user runs one command once, and demux keeps its
own hook set current in every running tmux server from then on.

Scope is tmux — hooks install --tool only accepts tmux.

What does this PR do

Replaces the paste-a-snippet model with a self-registering managed block.

• New demux hooks install --tool tmux writes a marker-delimited managed block
  to ~/.tmux.conf containing a single bootstrap line:

  # >>> demux managed block >>>
  set-hook -g client-attached "run-shell -b 'demux event client_attached 2>/dev/null; true'"
  # <<< demux managed block <<<
  

  It also registers the hook set in the live server immediately. The write is
  atomic (temp file + rename) and backs up the prior file to ~/.tmux.conf.demux-bak.
• On every tmux client attach, the bootstrap fires demux event client_attached,
  which reconciles demux's full canonical hook set into the running server:
  clears each event, re-adds the user's own (non-demux) entries, then re-adds
  demux's — idempotent, never stacks duplicates, self-heals after a demux upgrade.
  A version gate (@demux_hooks_version, a hash of the desired set) makes the
  steady-state attach a single tmux query.
• demux hooks install --print-only prints the bootstrap line without touching
  any file or server.
• Re-running hooks install is idempotent (replaces the block in place). If an
  older pasted multi-line snippet is detected outside the managed block, the user
  is prompted to remove it.
• New demux event subcommands name the tmux event rather than the reaction:
  window_focus, session_changed, new_window, client_attached. The hook
  handler decides the reaction (clear done-states, move the sidebar, reconcile
  slot panes).
• New config [sidebar.sticky] auto_show — when true, the sticky sidebar is
  shown automatically on client attach. Default false.
• Group commands (demux event, …) now reject an unknown subcommand with an
  error on stderr and a non-zero exit, instead of cobra's default of printing
  help to stdout with exit 0. Hooks run demux … 2>/dev/null; a since-removed
  subcommand now fails silently rather than dumping help text into a pane.
• demux hooks init is kept as a hidden, deprecated alias for
  hooks install --print-only.

Out of scope

• Tools other than tmux. hooks install --tool rejects anything but tmux;
  there is no shell/zsh integration in this iteration.

Manual QA

CLI feature. Verify by building the binary and driving demux hooks /
demux event against a tmux server, observing ~/.tmux.conf content and
tmux show-hooks -g output.

⚠️ demux hooks install mutates real state — ~/.tmux.conf and the live
tmux server. Do not run it bare during QA. Every scenario below runs the
binary against an isolated tmux server (tmux -L demuxqa) and a temp
$HOME, so your real config and real tmux server are never touched. The
$TMUX override is what redirects demux's tmux calls to the isolated server —
if you omit it, an empty/unset $TMUX routes to your default server.

Prerequisites

1. tmux 3.x+ is installed.

tmux -V

Expect tmux 3.x or next-3.x. The reconcile path was verified on next-3.7.

2. Go toolchain available to build the binary.

go version

Expect go1.2x. If missing, install Go or use a prebuilt demux binary from this branch.

Setup

Build the binary and stand up the isolated server + temp $HOME. Run this once;
later scenarios reuse $D, $QAHOME, $QATMUX.

mkdir -p /tmp/demux-qa && go build -o /tmp/demux-qa/demux .
export D=/tmp/demux-qa/demux
export QAHOME=$(mktemp -d /tmp/demux-qa-home.XXXXXX)

HOME="$QAHOME" tmux -L demuxqa new-session -d -s qa -x 200 -y 50
SOCK=$(tmux -L demuxqa display-message -p -t qa '#{socket_path}')
PID=$(tmux -L demuxqa display-message -p -t qa '#{pid}')
SID=$(tmux -L demuxqa display-message -p -t qa '#{session_id}')
export QATMUX="$SOCK,$PID,$SID"

# baseline: isolated server has no demux hooks
tmux -L demuxqa show-hooks -g | grep -c demux   # expect: 0

Scenario 1 — `--print-only` prints the bootstrap line, touches nothing

1. Run print-only:

   HOME="$QAHOME" $D hooks install --print-only

   Expected stdout, exit 0:

   set-hook -g client-attached "run-shell -b 'demux event client_attached 2>/dev/null; true'"
   

2. Confirm no file was written:

   ls "$QAHOME/.tmux.conf"

   Expected: No such file or directory.

Scenario 2 — `hooks install` writes the managed block and registers live hooks

1. Install into the isolated env:

   env HOME="$QAHOME" TMUX="$QATMUX" $D hooks install --tool tmux

   Expected stdout: Created <QAHOME>/.tmux.conf and
   Registered demux hooks in the live tmux server., exit 0.
2. Inspect the file:

   cat "$QAHOME/.tmux.conf"

   Expected: exactly the 3-line managed block (begin marker, set-hook -g client-attached …, end marker).
3. Inspect the live server:

   tmux -L demuxqa show-hooks -g | grep demux

   Expected: 7 lines — client-attached (bootstrap) plus after-kill-pane,
   after-new-window, after-select-pane, after-select-window,
   client-focus-in, client-session-changed.

Scenario 3 — re-running `hooks install` is idempotent

1. Run install a second time:

   env HOME="$QAHOME" TMUX="$QATMUX" $D hooks install --tool tmux

   Expected stdout: Updated <QAHOME>/.tmux.conf (backup: …/.tmux.conf.demux-bak).
2. File is still a single 3-line block:

   wc -l < "$QAHOME/.tmux.conf"          # expect: 3
   ls "$QAHOME/.tmux.conf.demux-bak"     # backup exists

3. No duplicate hooks on the server:

   tmux -L demuxqa show-hooks -g | grep demux | sed -E 's/\[[0-9]+\].*//' | sort | uniq -c

   Expected: every event shows count 1.

Scenario 4 — legacy pasted snippet is detected and removed on confirm

1. Stage a temp $HOME with an old-style snippet plus user-owned config:

   LH=$(mktemp -d /tmp/demux-qa-legacy.XXXXXX)
   printf '%s\n' \
     '# my own tmux config' \
     'set -g mouse on' \
     'set-hook -g after-select-pane "run-shell '\''demux event pane_focus 2>/dev/null; true'\''"' \
     'set-hook -ga client-session-changed "run-shell '\''demux sidebar follow'\''"' \
     'bind r source-file ~/.tmux.conf' > "$LH/.tmux.conf"

2. Install, answering y at the prompt:

   printf 'y\n' | env HOME="$LH" TMUX="$QATMUX" $D hooks install --tool tmux

   Expected: lists 2 legacy demux hook line(s) at L3/L4, prints
   Removed 2 legacy line(s).
3. Verify only the legacy hook lines were removed:

   cat "$LH/.tmux.conf"

   Expected: # my own tmux config, set -g mouse on, bind r … all retained;
   the two set-hook … demux … lines gone; managed block appended.
4. Cleanup: rm -rf "$LH".

Scenario 5 — end-to-end: a real client attach self-registers the full hook set

1. Clear the isolated server's hooks and source only ~/.tmux.conf (simulating
   a fresh server start that loads just the managed block):

   for ev in after-select-pane after-select-window client-session-changed \
             client-focus-in after-kill-pane after-new-window pane-exited \
             client-attached; do tmux -L demuxqa set-hook -gu "$ev" 2>/dev/null; done
   tmux -L demuxqa set -gu @demux_hooks_version 2>/dev/null
   tmux -L demuxqa source-file "$QAHOME/.tmux.conf"
   tmux -L demuxqa show-hooks -g | grep demux     # expect: only client-attached

2. Run the reconcile entry point directly (this is exactly what the bootstrap
   hook invokes on attach):

   env HOME="$QAHOME" TMUX="$QATMUX" $D event client_attached

3. Verify the full canonical set is now registered:

   tmux -L demuxqa show-hooks -g | grep demux
   tmux -L demuxqa show-hooks -g pane-exited
   tmux -L demuxqa show -gv @demux_hooks_version

   Expected: 7 event hooks present (including pane-exited, which the bare
   show-hooks -g dump omits — query it explicitly), and @demux_hooks_version
   set to a 12-hex-char hash.
4. Re-run demux event client_attached — the version gate makes it a no-op;
   show-hooks -g is unchanged, no duplicates.

Scenario 6 — reconcile preserves the user's own hooks (incl. `pane-exited`)

1. Seed a user-owned hook on pane-exited and on after-select-pane:

   tmux -L demuxqa set-hook -ga pane-exited 'run-shell "echo USER-pane-exited"'
   tmux -L demuxqa set-hook -ga after-select-pane 'run-shell "echo USER-select-pane"'
   tmux -L demuxqa set -gu @demux_hooks_version

2. Reconcile:

   env HOME="$QAHOME" TMUX="$QATMUX" $D event client_attached

3. Verify both user hooks survived at index [0], demux's at [1]:

   tmux -L demuxqa show-hooks -g pane-exited
   tmux -L demuxqa show-hooks -g after-select-pane

   Expected, for each event: [0] = the echo USER-… hook, [1] = the
   demux event … hook. (This is the case fixed by commit 643f13e — the bare
   show-hooks -g dump omits pane-exited, so reconcile queries each event
   individually to avoid wiping the user's hook.)

Scenario 7 — unknown subcommand fails on stderr, bare parent prints help

1. Unknown subcommand:

   HOME="$QAHOME" $D event bogus; echo "exit=$?"

   Expected: Error: unknown command "bogus" for "demux event" on stderr,
   exit=1, empty stdout.
2. Bare parent still prints help:

   HOME="$QAHOME" $D event; echo "exit=$?"

   Expected: help text on stdout, exit=0.

Teardown

tmux -L demuxqa kill-server
rm -rf "$QAHOME" /tmp/demux-qa /tmp/demux-qa-home.* /tmp/demux-qa-legacy.*

-L demuxqa is a dedicated test server created in Setup — killing it does not
affect your real tmux server.