gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add bounded Panama recovery actions

Browse Source
This commit is contained in:
Gabriel Brown
2026-08-18 10:35:18 -04:00
parent d855a26bd9
commit 2cc109f5e1
6 changed files with 596 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/quickshell/health-service-contract.sh
+83 -7
View File
@@ -75,15 +75,26 @@ fixture_dir="$(mktemp -d /tmp/panama-health.XXXXXX)"
helper="$fixture_dir/panama-doctor"
copy_bin="$fixture_dir/bin"
copy_file="$fixture_dir/copied-report.json"
repair_mode_file="$fixture_dir/repair-mode"
repair_log="$fixture_dir/repair.log"
notification_log="$fixture_dir/notifications.log"
printf 'success\n' >"$repair_mode_file"
printf '%s\n' \
'#!/usr/bin/env bash' \
'printf "%s\n" "$*" >>"$PANAMA_HEALTH_REPAIR_LOG"' \
'if [[ "$1" == "--json" ]]; then' \
' sleep 0.2' \
" printf '%s\\n' '$warning_snapshot'" \
' exit 0' \
'fi' \
'if [[ "$1" == "--repair" && "$2" == "panama.caffeine" && "$3" == "--json" ]]; then' \
' exit 0' \
' sleep 0.25' \
' case "$(cat "$PANAMA_HEALTH_REPAIR_MODE_FILE")" in' \
' success) printf "{\"schemaVersion\":1,\"checkId\":\"panama.caffeine\",\"accepted\":true,\"exitCode\":0,\"message\":\"Duplicate inhibitors were released.\"}\\n"; exit 0 ;;' \
' failed) printf "{\"schemaVersion\":1,\"checkId\":\"panama.caffeine\",\"accepted\":true,\"exitCode\":7,\"message\":\"Duplicate inhibitors could not be released.\"}\\n"; exit 7 ;;' \
' mismatch) printf "{\"schemaVersion\":1,\"checkId\":\"desktop.vicinae\",\"accepted\":true,\"exitCode\":0,\"message\":\"Wrong row.\"}\\n"; exit 0 ;;' \
' *) printf "not-json\\n"; exit 0 ;;' \
' esac' \
'fi' \
'exit 2' >"$helper"
chmod +x "$helper"
@@ -91,9 +102,16 @@ mkdir -p "$copy_bin"
printf '%s\n' \
'#!/usr/bin/env bash' \
'/usr/bin/cat > "$PANAMA_HEALTH_COPY_FILE"' >"$copy_bin/wl-copy"
chmod +x "$copy_bin/wl-copy"
printf '%s\n' \
'#!/usr/bin/env bash' \
'printf "%s\n" "$*" >>"$PANAMA_HEALTH_NOTIFICATION_LOG"' >"$copy_bin/notify-send"
chmod +x "$copy_bin/wl-copy" "$copy_bin/notify-send"
run() { PATH="$copy_bin:$PATH" PANAMA_HEALTH_HELPER="$helper" PANAMA_HEALTH_COPY_FILE="$copy_file" qs -p "$harness" "$@"; }
run() {
PATH="$copy_bin:$PATH" PANAMA_HEALTH_HELPER="$helper" PANAMA_HEALTH_COPY_FILE="$copy_file" \
PANAMA_HEALTH_REPAIR_MODE_FILE="$repair_mode_file" PANAMA_HEALTH_REPAIR_LOG="$repair_log" \
PANAMA_HEALTH_NOTIFICATION_LOG="$notification_log" qs -p "$harness" "$@"
}
harness_pid=""
cleanup() {
@@ -103,6 +121,8 @@ cleanup() {
trap cleanup EXIT
PATH="$copy_bin:$PATH" PANAMA_HEALTH_HELPER="$helper" PANAMA_HEALTH_COPY_FILE="$copy_file" \
PANAMA_HEALTH_REPAIR_MODE_FILE="$repair_mode_file" PANAMA_HEALTH_REPAIR_LOG="$repair_log" \
PANAMA_HEALTH_NOTIFICATION_LOG="$notification_log" \
qs -p "$harness" --daemonize >/dev/null
for _ in $(seq 1 40); do
run ipc show 2>/dev/null | rg -q '^target health-test$' && break
@@ -165,25 +185,81 @@ done
jq -e '.busy == false and .generation == ($before + 2) and .queuedRefresh == false' --argjson before "$before_generation" \
>/dev/null <<<"$state" || fail "queued refresh did not run exactly once: $state"
printf 'success\n' >"$repair_mode_file"
repair_generation="$(jq -r .generation <<<"$state")"
[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
|| fail 'repairable check was refused'
run ipc call health-test queue >/dev/null
working_state="$(run ipc call health-test status)"
jq -e '.repairingId == "panama.caffeine" and .queuedRefresh == true
and (.checkStates[] | select(.id == "panama.caffeine") | .status) == "warning"' \
>/dev/null <<<"$working_state" || fail "repair did not retain the degraded row while working: $working_state"
for _ in $(seq 1 120); do
state="$(run ipc call health-test status)"
jq -e '.busy == false and .generation == ($before + 3)' --argjson before "$before_generation" \
jq -e '.busy == false and .generation == ($before + 1) and .queuedRefresh == false' --argjson before "$repair_generation" \
>/dev/null <<<"$state" && break
sleep 0.1
done
jq -e '.busy == false and .generation == ($before + 3)' --argjson before "$before_generation" \
>/dev/null <<<"$state" || fail "accepted repair did not trigger one rescan: $state"
jq -e '.busy == false and .generation == ($before + 1) and .queuedRefresh == false
and .lastRepair == {schemaVersion:1, checkId:"panama.caffeine", accepted:true, exitCode:0, message:"Duplicate inhibitors were released."}
and (.checkStates[] | select(.id == "panama.caffeine") | .status) == "warning"' \
--argjson before "$repair_generation" >/dev/null <<<"$state" \
|| fail "accepted repair was trusted before exactly one observed rescan: $state"
# A syntactically valid command failure remains inline for Settings and still
# receives exactly one observed rescan.
printf 'failed\n' >"$repair_mode_file"
failure_generation="$(jq -r .generation <<<"$state")"
[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
|| fail 'second repairable check was refused'
for _ in $(seq 1 120); do
state="$(run ipc call health-test status)"
jq -e '.busy == false and .generation == ($before + 1)' --argjson before "$failure_generation" \
>/dev/null <<<"$state" && break
sleep 0.1
done
jq -e '.lastRepair.checkId == "panama.caffeine"
and .lastRepair.accepted == true and .lastRepair.exitCode == 7
and .lastRepair.message == "Duplicate inhibitors could not be released."
and .generation == ($before + 1)' --argjson before "$failure_generation" \
>/dev/null <<<"$state" || fail "known repair failure was not retained inline: $state"
[[ ! -e "$notification_log" || ! -s "$notification_log" ]] \
|| fail 'Settings-originated repair emitted an external notification'
# A malformed or mismatched helper response is contained and cannot masquerade
# as recovery; it also schedules only one scan.
printf 'mismatch\n' >"$repair_mode_file"
mismatch_generation="$(jq -r .generation <<<"$state")"
[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
|| fail 'mismatch repair fixture was refused'
for _ in $(seq 1 120); do
state="$(run ipc call health-test status)"
jq -e '.busy == false and .generation == ($before + 1)' --argjson before "$mismatch_generation" \
>/dev/null <<<"$state" && break
sleep 0.1
done
jq -e '.lastRepair.checkId == "panama.caffeine" and .lastRepair.accepted == false
and .lastRepair.exitCode == 0 and .generation == ($before + 1)' \
--argjson before "$mismatch_generation" >/dev/null <<<"$state" \
|| fail "mismatched repair JSON escaped containment: $state"
[[ "$(run ipc call health-test repair unknown.check)" == "false" ]] \
|| fail 'unknown check started a repair'
[[ "$(run ipc call health-test repair integration.calendar)" == "false" ]] \
|| fail 'non-repairable check started a repair'
state="$(run ipc call health-test status)"
jq -e '.repairingId == "" and .generation == ($before + 3)' --argjson before "$before_generation" \
jq -e '.repairingId == "" and .generation == ($before + 1)' --argjson before "$mismatch_generation" \
>/dev/null <<<"$state" || fail "rejected repair altered process state: $state"
python3 - "$service" <<'PY' || fail 'external repair failure notification is not bounded'
import sys
source = open(sys.argv[1], encoding="utf-8").read()
assert 'if (failed && external && !failureNotification.running)' in source
assert '"notify-send", "-a", "Panama", "-i", "dialog-error-symbolic"' in source
assert '"Panama action failed", "The requested health repair could not be completed."' in source
PY
trap - EXIT
cleanup
printf 'health service contract: PASS\n'
tests/quickshell/health-ui-contract.sh
+35 -1
View File
@@ -114,6 +114,11 @@ cp -a "$repo_dir/config/dot/quickshell" "$config_path"
cat >"$helper" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
if [[ "${1:-}" == "--repair" ]]; then
sleep 0.35
printf '{"schemaVersion":1,"checkId":"%s","accepted":true,"exitCode":7,"message":"The authored repair failed."}\n' "$2"
exit 7
fi
sleep 1.5
printf '%s\n' "$PANAMA_HEALTH_FIXTURE"
EOF
@@ -296,13 +301,42 @@ jq -e '
and (.focusChain | any(startswith("health-row-action:")))
' >/dev/null <<<"$settled_state" || fail "actual focus-chain traversal does not reach hero and row actions: $settled_state"
settled_heights="$(jq -c .rowHeights <<<"$settled_state")"
[[ "$(run ipc call health-ui-test request desktop.vicinae)" == "true" ]] \
|| fail 'inline repair fixture could not be requested'
working_repair_state="$(run ipc call health-ui-test state)"
jq -e '.renderedRows[] | select(.id == "desktop.vicinae") | .statusText == "Working…"' \
>/dev/null <<<"$working_repair_state" || fail "repair row did not show Working state: $working_repair_state"
[[ "$(jq -c .rowHeights <<<"$working_repair_state")" == "$settled_heights" ]] \
|| fail 'repair Working state changed row geometry'
for _ in $(seq 1 40); do
failed_repair_state="$(run ipc call health-ui-test state)"
jq -e '.renderedRows[] | select(.id == "desktop.vicinae") | .statusText == "Repair failed"' \
>/dev/null <<<"$failed_repair_state" && break
sleep 0.1
done
jq -e '.renderedRows[] | select(.id == "desktop.vicinae") | .statusText == "Repair failed"' \
>/dev/null <<<"$failed_repair_state" || fail "repair failure was not shown inline: $failed_repair_state"
[[ "$(jq -c .rowHeights <<<"$failed_repair_state")" == "$settled_heights" ]] \
|| fail 'repair failure changed row geometry'
[[ "$(jq -r '.renderedRows | map(.id) | unique | length' <<<"$failed_repair_state")" == 6 ]] \
|| fail 'repair state duplicated a health action row'
for _ in $(seq 1 40); do
failed_repair_state="$(run ipc call health-ui-test state)"
[[ "$(jq -r .checking <<<"$failed_repair_state")" == "false" ]] && break
sleep 0.1
done
[[ "$(jq -r .checking <<<"$failed_repair_state")" == "false" ]] \
|| fail 'post-repair scan did not settle before the next action'
[[ "$(run ipc call health-ui-test request desktop.quickshell)" == "true" ]] \
|| fail 'restart confirmation fixture could not be requested'
confirmation_state="$(run ipc call health-ui-test state)"
jq -e '
.confirmationVisible == true
and .confirmationId == "desktop.quickshell"
and .activatedRows == ["health-check-row:issue:desktop.quickshell"]
and (.activatedRows | index("health-check-row:issue:desktop.quickshell")) != null
and (.activatedRows | map(select(endswith(":desktop.quickshell"))) | length) == 1
' \
>/dev/null <<<"$confirmation_state" || fail 'Quickshell restart did not open confirmation sheet'
tests/quickshell/panama-doctor-contract.sh
+193
View File
@@ -235,4 +235,197 @@ summary="$(run_doctor --summary)"
[[ "$summary" =~ ^Panama\ system\ health:\ (healthy|warning|error)\ \([0-9]+\ ok,\ [0-9]+\ warnings,\ [0-9]+\ errors,\ [0-9]+\ unconfigured\)$ ]] \
|| fail "summary is not concise: $summary"
# Repairs run against a second, disposable Panama root. Every process boundary
# records its argv, and every filesystem assertion is confined to this fixture.
repair_root="$fixture/repair-root"
repair_log="$runtime_dir/repair.log"
mkdir -p "$repair_root/config/dot" "$repair_root/setup/scripts"
for name in hypr quickshell uwsm vicinae; do
mkdir -p "$repair_root/config/dot/$name"
done
mv "$bin_dir/systemctl" "$bin_dir/systemctl-probe"
cat >"$bin_dir/systemctl" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
if [[ "${1:-}" == "--user" && "${2:-}" == "restart" ]]; then
printf 'systemctl' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
[[ ! -e "$XDG_RUNTIME_DIR/fail-repair" ]] || exit 5
exit 0
fi
exec "${0%/*}/systemctl-probe" "$@"
EOF
cat >"$bin_dir/panama-action" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'panama-action' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
EOF
cat >"$bin_dir/kill" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'kill' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
EOF
cat >"$bin_dir/systemd-inhibit" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'systemd-inhibit' >>"$XDG_RUNTIME_DIR/repair.log"
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
uid="$(/usr/bin/id -u)"
printf 'Panama %s fixture-user 4101 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
printf 'Panama %s fixture-user 4102 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
printf 'Other %s fixture-user 4999 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
printf 'Panama 99999 fixture-user 4998 systemd-inhibit sleep:idle Caffeine block\n'
printf 'Panama %s fixture-user 4997 systemd-inhibit sleep:idle Other block\n' "$uid"
printf 'Panama %s fixture-user 4996 systemd-inhibit sleep:idle Caffeine delay\n' "$uid"
EOF
cat >"$repair_root/setup/scripts/link-vicinae-scripts" <<'EOF'
#!/usr/bin/bash
set -euo pipefail
printf 'link-vicinae-scripts|%s' "$0" >>"$XDG_RUNTIME_DIR/repair.log"
if (( $# > 0 )); then
printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
fi
printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
EOF
chmod +x "$bin_dir/systemctl" "$bin_dir/panama-action" "$bin_dir/kill" \
"$bin_dir/systemd-inhibit" "$repair_root/setup/scripts/link-vicinae-scripts"
run_repair() {
HOME="$home" \
PATH="$bin_dir" \
XDG_CURRENT_DESKTOP=Hyprland \
PANAMA_DOCTOR_ROOT="$repair_root" \
PANAMA_DOCTOR_HOME="$home" \
PANAMA_DOCTOR_CONFIG_HOME="$config_home" \
PANAMA_DOCTOR_STATE_HOME="$state_home" \
PANAMA_DOCTOR_RUNTIME_DIR="$runtime_dir" \
PANAMA_DOCTOR_PATH="$bin_dir" \
PANAMA_DOCTOR_TIMEOUT=0.2 \
/usr/bin/python3 "$doctor" "$@"
}
repair_output=""
repair_status=0
invoke_repair() {
set +e
repair_output="$(run_repair --repair "$1" --json)"
repair_status=$?
set -e
}
assert_repair_result() {
local id="$1" accepted="$2" exit_code="$3"
jq -e --arg id "$id" --argjson accepted "$accepted" --argjson exitCode "$exit_code" '
(keys | sort) == ["accepted", "checkId", "exitCode", "message", "schemaVersion"]
and .schemaVersion == 1
and .checkId == $id
and .accepted == $accepted
and .exitCode == $exitCode
and (.message | type == "string" and length > 0)
' >/dev/null <<<"$repair_output" || fail "invalid repair result for $id: $repair_output"
}
for repair_case in \
'desktop.hyprpaper|systemctl|--user|restart|hyprpaper.service' \
'desktop.hypridle|systemctl|--user|restart|hypridle.service' \
'desktop.vicinae|systemctl|--user|restart|vicinae.service' \
'desktop.quickshell|panama-action|restart-shell'; do
IFS='|' read -r repair_id executable arg1 arg2 arg3 <<<"$repair_case"
: >"$repair_log"
invoke_repair "$repair_id"
[[ "$repair_status" == 0 ]] || fail "$repair_id returned $repair_status"
assert_repair_result "$repair_id" true 0
expected="$executable|$arg1"
[[ -z "$arg2" ]] || expected+="|$arg2"
[[ -z "$arg3" ]] || expected+="|$arg3"
[[ "$(<"$repair_log")" == "$expected" ]] \
|| fail "$repair_id argv was not exact: $(<"$repair_log")"
done
# Known process failures still return complete JSON and preserve the command's
# exit status for the QML state machine.
touch "$runtime_dir/fail-repair"
: >"$repair_log"
invoke_repair desktop.vicinae
rm "$runtime_dir/fail-repair"
[[ "$repair_status" == 5 ]] || fail "failed repair returned $repair_status instead of 5"
assert_repair_result desktop.vicinae true 5
[[ "$(<"$repair_log")" == 'systemctl|--user|restart|vicinae.service' ]] \
|| fail 'failed repair changed the authored argv'
# The Vicinae repair executes only the authored setup helper with no arguments.
: >"$repair_log"
invoke_repair panama.vicinae-commands
[[ "$repair_status" == 0 ]] || fail "Vicinae command repair returned $repair_status"
assert_repair_result panama.vicinae-commands true 0
[[ "$(<"$repair_log")" == "link-vicinae-scripts|$repair_root/setup/scripts/link-vicinae-scripts" ]] \
|| fail "Vicinae command repair argv was not exact: $(<"$repair_log")"
# Runtime-link repair may replace only the four authored symlink names. Broken
# or absent links are recreated toward authored tracked destinations; regular
# files and directories remain untouched and make the result incomplete.
for name in hypr quickshell uwsm vicinae; do
path="$config_home/$name"
if [[ -e "$path" || -L "$path" ]]; then
mv "$path" "$fixture/pre-repair-$name"
fi
done
ln -s "$fixture/missing-hypr" "$config_home/hypr"
ln -s "$fixture/missing-quickshell" "$config_home/quickshell"
printf 'user-owned file\n' >"$config_home/uwsm"
mkdir "$config_home/vicinae"
ln -s "$fixture/untouched" "$config_home/not-panama"
: >"$repair_log"
invoke_repair panama.runtime-links
[[ "$repair_status" == 1 ]] || fail "blocked runtime-link repair returned $repair_status"
assert_repair_result panama.runtime-links true 1
[[ -L "$config_home/hypr" && "$(readlink "$config_home/hypr")" == "$repair_root/config/dot/hypr" ]] \
|| fail 'hypr link was not recreated toward its authored destination'
[[ -L "$config_home/quickshell" && "$(readlink "$config_home/quickshell")" == "$repair_root/config/dot/quickshell" ]] \
|| fail 'quickshell link was not recreated toward its authored destination'
[[ -f "$config_home/uwsm" && "$(<"$config_home/uwsm")" == 'user-owned file' ]] \
|| fail 'runtime-link repair replaced a regular file'
[[ -d "$config_home/vicinae" && ! -L "$config_home/vicinae" ]] \
|| fail 'runtime-link repair replaced a user-owned directory'
[[ -L "$config_home/not-panama" && "$(readlink "$config_home/not-panama")" == "$fixture/untouched" ]] \
|| fail 'runtime-link repair touched an unauthored link name'
[[ ! -s "$repair_log" ]] || fail 'runtime-link repair launched a process'
# Caffeine repair parses exact authored metadata, keeps the first valid lock,
# and releases only later exact matches.
: >"$repair_log"
invoke_repair panama.caffeine
[[ "$repair_status" == 0 ]] || fail "Caffeine repair returned $repair_status"
assert_repair_result panama.caffeine true 0
expected_caffeine=$'systemd-inhibit|--list|--no-pager|--no-legend\nkill|--|4102'
[[ "$(<"$repair_log")" == "$expected_caffeine" ]] \
|| fail "Caffeine repair did not preserve/filter exact inhibitors: $(<"$repair_log")"
# Rejected IDs are complete JSON, exit 2, and cause neither a process launch
# nor a filesystem mutation.
fixture_state() {
find "$config_home" -mindepth 1 -printf '%P|%y|%l\n' | sort | sha256sum | awk '{print $1}'
}
for rejected_id in unknown.check integration.home-assistant input.brightness \
desktop.notifications ../../escape 'desktop.vicinae;touch injected'; do
: >"$repair_log"
before_state="$(fixture_state)"
invoke_repair "$rejected_id"
[[ "$repair_status" == 2 ]] || fail "$rejected_id returned $repair_status instead of 2"
assert_repair_result "$rejected_id" false 2
[[ ! -s "$repair_log" ]] || fail "$rejected_id launched a process"
[[ "$(fixture_state)" == "$before_state" ]] || fail "$rejected_id mutated the filesystem"
done
printf 'panama doctor contract: PASS\n'