Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,15 @@ jobs:
chmod +x tests/test_alias_parity.sh
bash tests/test_alias_parity.sh

- name: Check shutdown helper syntax (Bash and Zsh)
run: |
bash --noprofile --norc -n config/dotfiles/.aliases
zsh -df -n config/dotfiles/.aliases
bash --noprofile --norc -n tests/test_shutdown_helpers.sh

- name: Run isolated shutdown helper tests (Bash and Zsh)
run: bash tests/test_shutdown_helpers.sh --bash "$(command -v bash)" --zsh "$(command -v zsh)"

- name: Run idempotency test suite
run: bash tests/test_idempotency.sh

Expand Down Expand Up @@ -183,6 +192,16 @@ jobs:
bash setup.sh
echo "Second run completed without errors"

- name: Check shutdown helper syntax (system Bash 3.2 and Zsh)
run: |
/bin/bash --version
/bin/bash --noprofile --norc -n config/dotfiles/.aliases
/bin/zsh -df -n config/dotfiles/.aliases
/bin/bash --noprofile --norc -n tests/test_shutdown_helpers.sh

- name: Run isolated shutdown helper tests (system Bash 3.2 and Zsh)
run: /bin/bash tests/test_shutdown_helpers.sh --bash /bin/bash --zsh /bin/zsh

- name: Run tool version tests
run: bash tests/test_tool_versions.sh

Expand Down Expand Up @@ -236,6 +255,9 @@ jobs:
- name: Lint config/dotfiles/.aliases
run: shellcheck -s bash config/dotfiles/.aliases

- name: Lint isolated shutdown helper harness
run: shellcheck tests/test_shutdown_helpers.sh

- name: Run Bash flag compatibility gates
run: bash tests/test_setup_flags.sh

Expand Down
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Isolated shutdown-helper regression coverage under Bash/Zsh on Linux/macOS,
including macOS system Bash 3.2, with non-forwarding command stubs. (#514)

### Changed

- Interactive tool pickers use Quiet Accent semantic colors when a compatible console is available,
while preserving ASCII/plain output for redirected sessions and `NO_COLOR`. (#507)
- Bash/Zsh `tsdn` now requires exactly one canonical positive decimal minute
argument, rejects WSL delays above 5,256,000 minutes before conversion, and
warns that positive Windows timeouts force application closure and risk
unsaved work. Native minute strings remain unconverted. (#514)

### Fixed

- Route Bash/Zsh `sdn`, `tsdn`, and `cancel_tsdn` to the Windows host when a
Microsoft kernel marker identifies WSL, without native fallback on interop
failure. Preserve native Linux/macOS commands; deliberately reject conflicting
WSL environment hints on non-Microsoft Linux kernels and indeterminate or
unsupported platforms. Document custom-kernel/container detection limits. (#514)
- Preserve actual cancellation diagnostics and failure status instead of
reporting every failure as "no pending shutdown" success. Cancellation remains
system-wide. (#514)

### Removed

- Embedded squad infrastructure: removed `.squad/` directory and all internal AI-agent coordination tooling from the repository. Project coordination now handled externally. (PR #475, PR #477)
Expand Down
65 changes: 64 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ Full definitions:

## Shell Functions

Three helper functions are available after setup:
The following helper functions are available after setup:

### Linux / macOS / WSL

Expand All @@ -298,6 +298,69 @@ create_tmux
start_up
```

#### Shutdown helpers (Bash/Zsh)

**`sdn`** requests immediate shutdown, **`tsdn <minutes>`** schedules shutdown,
and **`cancel_tsdn`** cancels a pending shutdown system-wide (not just requests
created by these helpers). In WSL they target the **Windows host**, not just the
Linux distribution. Native Linux/macOS keep their existing commands:

| Helper | WSL (Windows host) | Native Linux | macOS |
|--------|--------------------|--------------|-------|
| `sdn` | `shutdown.exe /s /t 0` | `sudo shutdown -h now` | `sudo shutdown -h now` |
| `tsdn M` | `shutdown.exe /s /t S` (`S = M * 60`) | `sudo shutdown -h +M` | `sudo shutdown -h +M` |
| `cancel_tsdn` | `shutdown.exe /a` | `sudo shutdown -c` | `sudo killall shutdown` |

`tsdn` requires **exactly one positive decimal integer with no leading zeros**
(for example, `1` or `30`). Missing/extra arguments, zero, negatives, fractions,
and nonnumeric input fail without running a shutdown command. WSL accepts up to
**5,256,000 minutes** (315,360,000 seconds); larger values are rejected before
arithmetic. Native Linux/macOS receive the original minute string without
conversion or the Windows ceiling; their own command limits still apply.

> **Windows data-loss warning:** A positive Windows `/t` timeout implicitly
> forces applications to close, even without `/f`, and unsaved work may be lost.
> WSL timed requests emit this warning to stderr. There is no extra confirmation.
> See Microsoft's [`shutdown` reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/shutdown).
> A zero-timeout request is not a guarantee of instantaneous power-off.

Platform selection happens only when a helper is invoked, using `uname -s` and,
on Linux only, a successful nonempty read of `/proc/version`:

| Detection | Result |
|-----------|--------|
| Linux + case-insensitive Microsoft kernel marker | WSL, even when both WSL environment variables are absent |
| Linux + non-Microsoft kernel + `WSL_DISTRO_NAME` and `WSL_INTEROP` both unset/empty | Native Linux, even if `shutdown.exe` is on PATH |
| Linux + non-Microsoft kernel + either WSL variable nonempty | Ambiguous: diagnostic, nonzero status, no operation |
| Linux + missing/unreadable/empty/failed kernel probe | Indeterminate: diagnostic, nonzero status, no operation, regardless of WSL variables |
| Darwin | macOS; inherited WSL variables are ignored and `/proc/version` is not read |
| Unsupported OS or failed OS probe | Diagnostic, nonzero status, no operation |

Stale WSL variables on native Linux are **intentionally rejected** as ambiguous.
Establish the actual platform and correct the environment manually; the helpers
never clear variables or retry automatically. This is a **heuristic, not a
security boundary**: custom WSL kernels without the Microsoft marker are
ambiguous when WSL hints remain, but indistinguishable from native Linux when
all hints are removed. Custom kernels and nested containers are outside initial
coverage; do not assume universal or fail-safe detection.

WSL requires `shutdown.exe` on PATH and Windows-process interop enabled. The
helpers check command availability without executing a probe. Missing interop
or execution failures **never fall back to Linux shutdown**, use a hard-coded
Windows drive path, or automatically abort/reschedule. Actual command output
and exit status are preserved, including permission and cancellation failures;
not every cancellation failure means "no pending shutdown." Shell exit codes
are not interpreted as Win32 error numbers. The native PowerShell profile is
unchanged by this Bash/Zsh routing contract.

The isolated regression suite is `bash tests/test_shutdown_helpers.sh`; it
requires both Bash and Zsh (optional `--bash /absolute/path` and
`--zsh /absolute/path`). It extracts only the production helper definitions and
uses non-forwarding recording stubs, never real shutdown commands. Linux/macOS
CI includes both shells and macOS system Bash 3.2. These simulated tests do not
prove live WSL or OS-level shutdown behavior; do not validate with a live
schedule-then-cancel experiment.

### Windows

**`New-PsmuxSession`** -- Create or attach to the `tank_dev` psmux session (Windows equivalent of `create_tmux`).
Expand Down
81 changes: 67 additions & 14 deletions config/dotfiles/.aliases
Original file line number Diff line number Diff line change
Expand Up @@ -162,30 +162,83 @@ start_up() {
create_tmux
}

# ── Shutdown (requires sudo on Linux/macOS) ──────────────────────────────────
# ── Shutdown (Windows host on WSL; sudo on native Linux/macOS) ────────────────

# Heuristic detection, evaluated only on invocation. WSL environment variables
# are ambiguity hints, not authority; custom kernels/containers have limits.
_dev_setup_shutdown_platform() {
local os kernel
if ! os=$(uname -s); then
printf '%s\n' 'shutdown helpers: unable to detect OS with uname -s' >&2
return 1
fi
case "$os" in
Linux)
if ! kernel=$(cat /proc/version 2>/dev/null) || [[ -z "$kernel" ]]; then
printf '%s\n' 'shutdown helpers: unable to read a nonempty /proc/version; platform is indeterminate' >&2
return 1
fi
case "$kernel" in
*[Mm][Ii][Cc][Rr][Oo][Ss][Oo][Ff][Tt]*)
if ! command -v shutdown.exe >/dev/null 2>&1; then
printf '%s\n' 'shutdown helpers: WSL requires shutdown.exe on PATH and Windows interop enabled' >&2
return 1
fi
printf '%s\n' wsl
;;
*)
if [[ -n "${WSL_DISTRO_NAME:-}" || -n "${WSL_INTEROP:-}" ]]; then
printf '%s\n' 'shutdown helpers: ambiguous platform: Linux kernel lacks Microsoft marker but WSL_DISTRO_NAME or WSL_INTEROP is set; verify the platform and correct the environment manually' >&2
return 1
fi
printf '%s\n' linux
;;
esac
;;
Darwin) printf '%s\n' macos ;;
*) printf 'shutdown helpers: unsupported OS: %s\n' "$os" >&2; return 1 ;;
esac
}

# Shut down immediately
# Shut down immediately. WSL interop failures never fall back to native shutdown.
sdn() {
sudo shutdown -h now
local platform
platform=$(_dev_setup_shutdown_platform) || return $?
case "$platform" in
wsl) shutdown.exe /s /t 0 ;;
linux|macos) sudo shutdown -h now ;;
esac
}

# Timed shutdown — usage: tsdn <minutes>
tsdn() {
if [[ ! "$1" =~ ^[1-9][0-9]*$ ]]; then
echo "tsdn: minutes must be a positive integer"
if [[ $# -ne 1 || ! "${1:-}" =~ ^[1-9][0-9]*$ ]]; then
printf '%s\n' 'tsdn: usage: tsdn <minutes> (one positive decimal integer, no leading zeros)' >&2
return 1
fi
sudo shutdown -h +"$1"
local platform minutes="$1"
platform=$(_dev_setup_shutdown_platform) || return $?
case "$platform" in
wsl)
# Bound the decimal string before arithmetic (also safe on Bash 3.2).
if [[ ${#minutes} -gt 7 ]] || [[ ${#minutes} -eq 7 && "$minutes" -gt 5256000 ]]; then
printf '%s\n' 'tsdn: WSL delay must not exceed 5256000 minutes' >&2
return 1
fi
printf '%s\n' 'tsdn: warning: a positive Windows timeout forces applications to close; unsaved work may be lost.' >&2
shutdown.exe /s /t "$((minutes * 60))"
;;
linux|macos) sudo shutdown -h +"$minutes" ;;
esac
}

# Cancel a pending timed shutdown (OS-aware)
# Cancel a pending shutdown system-wide, preserving the command's diagnostics/status.
cancel_tsdn() {
case "$(uname)" in
Linux*) cmd="sudo shutdown -c" ;;
Darwin*) cmd="sudo killall shutdown" ;;
*) echo "cancel_tsdn: unsupported OS"; return 1 ;;
local platform
platform=$(_dev_setup_shutdown_platform) || return $?
case "$platform" in
wsl) shutdown.exe /a ;;
linux) sudo shutdown -c ;;
macos) sudo killall shutdown ;;
esac
if ! eval "$cmd" 2>/dev/null; then
echo "No pending shutdown to cancel."
fi
}
1 change: 1 addition & 0 deletions tests/test_alias_parity.sh
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ ALLOWED_ALIAS_DRIFT=(
"touch:windows" # Set-FileTimestamp -- Windows-specific override
"start_up:linux" # shell startup function -- Linux-specific
"create_tmux:linux" # tmux session create -- Linux uses tmux directly
"_dev_setup_shutdown_platform:linux" # Private Bash/Zsh WSL/native shutdown selector
"New-PsmuxSession:windows" # Windows equivalent of create_tmux
# v5.2 profile-path resolution helpers (issue #441/#442) -- Windows-only PS
# internal functions; they query $PROFILE on PS hosts and have no Linux equiv.
Expand Down
Loading
Loading