feat(installer): ask before an upgrade ends live sessions - #1010

Root cause

scripts/install.sh:535 (on main) unconditionally force-stopped the daemon before the first
executable swap:

"$bindir/min" stop --force >/dev/null 2>&1 || true

Called from scripts/install.sh:650, before the mv -f of the first bin/lib component. So a
curl … | sh upgrade destroyed every live session with no signal and no way out. The daemon-side
mitigation ("minimald is shutting down and disconnecting") does not help: it is printed by the
daemon being replaced, so it only exists if you already upgraded past the release that added it,
and it is a notice after the fact rather than a decision point.

min stop already knows the answer — crates/minimal/src/lib.rs:2137:

bail!("daemon has active sessions; pass --force to shut down anyway")

The installer never asked it. It went straight to --force.

Fix

The pre-upgrade stop is now graceful-first (scripts/install.sh:597):

if _stop_out="$("$bindir/min" stop 2>&1 </dev/null)"; then
    return 0
fi
case "$_stop_out" in
    *"$sessions_live_msg"*) confirm_force_stop || return 1 ;;
esac
# Any other failure falls through to the force stop, silent as before.

Design choices and why:

• Matched on the message, not the exit status (sessions_live_msg, scripts/install.sh:567).
  A bare non-zero from min stop also means no daemon, a failed connect, a min too old to know
  the subcommand, or a transport drop on an otherwise successful stop. Gating on the exit code
  would turn every upgrade into a prompt and would fail installs that are otherwise fine. Only the
  active-sessions refusal escalates; everything else keeps today's silent, best-effort behaviour
  and still falls through to the force stop.
• Answer read from the controlling terminal, never stdin (confirm_force_stop,
  scripts/install.sh:576). Under curl … | sh stdin is the script; reading it would consume the
  installer. Inside the component loop stdin is the applicable-manifest file, which is worse.
  ${MINIMAL_OVERRIDE_TTY:-/dev/tty} is the source; the harness overrides it.
• No terminal means abort, not force and not hang. (exec <"$_tty") 2>/dev/null probes
  openability; if there is nobody to consent the run exits non-zero naming the escape hatch.
• Escape hatch is --force-stop or a non-empty MINIMAL_INSTALL_FORCE_STOP
  (scripts/install.sh:74, :97). Deliberately not --force, which already means "remove
  modified files too" in uninstall mode. The flag is filtered out of "$@" wherever it appears, so
  the target stays the sole positional.
• Declining aborts before the first executable swap (scripts/install.sh:736), dropping the
  temp download; no record is written. The message says no executables were replaced rather than
  "nothing was installed" — the stop fires at the first bin/lib row, so a data row ordered
  ahead of it in the manifest may already have been replaced, and the message claims only what the
  abort point actually guarantees.

The graceful-first path is also a strict improvement on the healthy case: an upgrade with no
sessions now stops cleanly and never force-stops at all.

crates/common/tests/installer_stop_signal.rs pins the cross-language coupling: it reads
scripts/install.sh and crates/minimal/src/lib.rs as text and asserts the installer's literal is
still present in the CLI source. Without it, rewording the bail! silently returns the installer to
an unconditional force-stop — the exact bug this PR fixes — with every installer test still green,
because the harness stubs min with its own copy of the string.

Acceptance

• Graceful min stop is attempted first, and its signal is reused rather than a parallel
  session check — scripts/install_test.sh:535 (H8 daemonupgrade): asserts the on-disk min
  is called with exactly stop, once, however many components are replaced, never escalating to
  --force, and asking nothing.
• An active-sessions refusal lists what is running and prompts —
  scripts/install_test.sh:601 (H16): asserts session-alpha appears in the output and that
  Continue? is asked.
• Only explicit confirmation falls through to min stop --force and continues the upgrade —
  scripts/install_test.sh:601 (H16, answer y): asserts stop then stop --force in
  stop.calls and that the replaced component hashes to the manifest value.
• Declining aborts — scripts/install_test.sh:616 (H17, answer n): exit 1, stop --force
  never called, the stale component still on disk, no *.tmp.* left behind, and the abort reports
  no executable was replaced.
• Non-interactive / CI invocations do not hang — scripts/install_test.sh:631 (H18, no
  openable terminal: exits non-zero naming the hatch, never prompts, never forces, installs
  nothing); :642 (H19, --force-stop: skips the graceful stop, asks nothing, completes); :652
  (H20, MINIMAL_INSTALL_FORCE_STOP, for a pipeline with no argv); :666 (H21, flag after the
  target: the target still resolves).
• No other min stop failure may prompt or fail the install —
  scripts/install_test.sh:572 (H9, a min too old, exiting 2 and writing to both streams): exit
  0, neither stream leaked, nothing asked, nothing listed, the upgrade completed, and it still fell
  through to stop --force.
• The signal cannot rot silently — crates/common/tests/installer_stop_signal.rs.

Non-vacuity was checked by mutation, not assumed. Against a scratch copy: reverting
stop_running_daemon to the unconditional force-stop → 13 failures; reading the answer from stdin
instead of /dev/tty → 3 failures; treating any non-zero stop as "sessions live" → 6 failures
(including H9's "a failing min stop does not fail the install"); dropping every positional in the
option filter → 7 failures, one of them H21's target 'unstable'; rewording sessions_live_msg →
installer_stop_signal fails with the intended message.

Test plan

Run on macOS arm64 (Darwin 25.4.0), all green on the committed tree:

/opt/homebrew/bin/shellcheck scripts/install.sh scripts/install_test.sh
  → clean

/opt/homebrew/bin/just test-installer
  → shellcheck --shell=sh: clean
  → install_test.sh under sh   (macOS bash 3.2 in POSIX mode): 244 passed, 0 failed
  → install_test.sh under dash:                                244 passed, 0 failed

/opt/homebrew/bin/just fmt-check          → clean
cargo clippy -p common --all-targets -- -D warnings → clean
cargo test -p common                      → 44 + 1 + 1 passed, 0 failed
  (includes tests/installer_stop_signal.rs and the pre-existing shell_lint gate)

just test-installer is the same gate ci-shell-installer runs, and the lane triggers: both
installer paths are in its path filter.

Delegated to CI (cannot run on macOS — minimald does not build here, so the workspace test suite
is out of reach locally, per AGENTS.md "Platform matrix"):

• ci-linux-native / ci-linux-kvm — the workspace test run, which is what actually executes
  crates/common/tests/installer_stop_signal.rs in CI. Verified locally with
  cargo test -p common; common has no minimald dependency, so this one is genuinely runnable
  on macOS and was run.
• ci — workspace rustfmt (run locally) and workspace clippy (only -p common runnable here; the
  new file is the only Rust change and it is in common).
• ci-macos — its scope is -p minvmd -p sessions; no Rust in either crate changed.

No CI lane executes install.sh itself (release.yml only uploads it; nightly.yml hand-assembles
the layout it would write), so no lane can newly block on the prompt.

Notes

• Two reviewer findings were deliberately not applied:
  • MINIMAL_INSTALL_FORCE_STOP=0 counts as "on" because the check is -n. Real footgun, but
    "non-empty" is the convention this file already uses for its env overrides
    (MINIMAL_INSTALL_TARGET_OVERRIDE, scripts/install.sh:499) and it is documented as non-empty
    in the usage header, the spec, and the guide. Changing the semantics of a knob is a separate,
    deliberate decision, not review cleanup.
  • A backgrounded pipeline (curl … | sh &) that still has a controlling terminal passes the
    openability probe and would then take SIGTTIN on the read, stopping rather than aborting.
    There is no portable way to detect foreground process-group membership in POSIX sh, and
    [ -t 0 ] is wrong under curl | sh. The documented escape hatch is the way out. Related to
    the SIGTTOU footgun already recorded in AGENTS.md.
• docs/specs/07-spec-installer/07-spec-installer.md R5.5 was rewritten to describe the new
  behaviour, plus a new user story under R2.1 for --force-stop. Spec prose is functional
  throughout — no issue numbers, PR numbers, or names.
• .github/workflows/ is untouched.

Closes gominimal/inbox#366

Summary by CodeRabbit

• New Features

  • Upgrades now detect active daemon sessions and ask for confirmation before stopping them.
  • Added --force-stop and MINIMAL_INSTALL_FORCE_STOP options for scripted or non-interactive upgrades.
  • Upgrades can proceed without prompts when forced; declined or unavailable confirmations safely abort before replacement.

• Documentation

  • Updated installation guidance and specifications to explain session handling and forced upgrades.

• Tests

  • Added coverage for interactive, non-interactive, forced, declined, and target-selection upgrade scenarios.