@sebastienrousseau/dotfiles 0.2.518 → 0.2.520

package/scripts/diagnostics/conflicts.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Alias/Command Conflicts Report
 # Usage: dot conflicts

package/scripts/diagnostics/doctor-unified.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Unified doctor orchestrator — parses flags and dispatches to existing scripts.
 set -euo pipefail
@@ -20,7 +20,11 @@ target="scripts/diagnostics/doctor.sh"
 for arg in "$@"; do
   case "$arg" in
     --heal | -H) target="scripts/ops/heal.sh" ;;
-    --audit | -a) target="scripts/ops/health-check.sh" ;;
+    # scripts/ops/health-check.sh has never existed in this tree, so
+    # `dot doctor --audit` died with "Script not found" for every user who
+    # tried it. The health dashboard is what that name meant: it is the
+    # audit-shaped diagnostic, and `dot health-check` already aliases it.
+    --audit | -a) target="scripts/diagnostics/health.sh" ;;
     --score | -s) target="scripts/diagnostics/scorecard.sh" ;;
     --smoke | -m) target="scripts/diagnostics/smoke-test.sh" ;;
     --drift | -d) target="scripts/diagnostics/drift-dashboard.sh" ;;

package/scripts/diagnostics/doctor.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## Dotfiles Doctor.
 ##
@@ -169,11 +169,11 @@ fi
 
 # --- AI CLIs ---
 _section "AI CLIs"
-for cmd in claude copilot kimi agy sgpt ollama opencode aider kiro-cli; do
+for cmd in codex claude copilot kimi agy sgpt ollama opencode aider kiro-cli; do
   if check_cmd "$cmd"; then
     _ok "$cmd" "$(pretty_path "$(get_cmd_path "$cmd")")"
   else
-    _warn "$cmd" "optional"
+    ui_info "$cmd" "optional (not installed)"
   fi
 done
 
@@ -372,7 +372,11 @@ fi
 
 # --- State ---
 _section "State"
-if chezmoi verify &>/dev/null; then
+# --exclude=always: a run_before_/run_after_ script (the macOS iCloud hook)
+# is "pending" on every apply by design, so plain `verify` exits 1 forever
+# on a fully synchronised machine. Files, dirs, symlinks and run_once/
+# run_onchange scripts still count.
+if chezmoi verify --exclude=always &>/dev/null; then
   _ok "chezmoi" "synchronized"
 else
   _fail "chezmoi" "drifted (run dot drift)"
@@ -462,28 +466,46 @@ else
   _fail "fish_plugins" "missing (~/.config/fish/fish_plugins)"
 fi
 
+# Only meaningful when there is a cargo for topgrade to run it through; a
+# machine without a Rust toolchain has nothing to update, so warning about
+# the missing helper there is noise that never goes away.
 if command -v cargo-install-update >/dev/null 2>&1; then
   _ok "cargo-install-update" "$(pretty_path "$(command -v cargo-install-update)")"
-else
+elif command -v cargo >/dev/null 2>&1; then
   _warn "cargo-install-update" "missing (install: cargo install cargo-update)"
+else
+  _ok "cargo-install-update" "not needed (cargo not installed)"
 fi
 
 # --- Symlinks ---
 broken_links=0
+broken_list=""
 for root in "$HOME/.config" "$HOME/.local/bin" "$HOME/.local/share" "$HOME/.ssh"; do
   [[ -d "$root" ]] || continue
   while IFS= read -r -d '' link; do
     link_name="$(basename "$link")"
     [[ "$link" == *"google-chrome-backup"* ]] && continue
     [[ "$link_name" == SingletonLock || "$link_name" == SingletonCookie || "$link_name" == SingletonSocket ]] && continue
-    [[ -e "$link" ]] || broken_links=$((broken_links + 1))
+    [[ -e "$link" ]] && continue
+    # A link into ~/Library/Caches dangling is macOS working as designed, not a
+    # health problem: the OS purges that directory whenever it wants the space,
+    # and the owning tool recreates its cache on next use. ~/.config/swiftpm/cache
+    # -> ~/Library/Caches/org.swift.swiftpm is the usual one; it was "fixed" by
+    # recreating the target earlier the same day and had broken again by evening,
+    # which is the tell that it is not fixable, only re-reported.
+    case "$(readlink "$link" 2>/dev/null)" in
+      "$HOME/Library/Caches/"*) continue ;;
+    esac
+    broken_links=$((broken_links + 1))
+    broken_list="${broken_list:+$broken_list, }$(pretty_path "$link")"
   done < <(find "$root" -maxdepth 3 -type l -print0 2>/dev/null)
 done
 
 if [[ $broken_links -eq 0 ]]; then
   _ok "symlinks" "none broken"
 else
-  _warn "symlinks" "$broken_links broken"
+  # Name them. "1 broken" with no path meant hunting for it by hand, twice.
+  _warn "symlinks" "$broken_links broken: $broken_list"
 fi
 
 # --- Portability ---
@@ -548,8 +570,10 @@ for tool in mise starship zoxide atuin fzf direnv; do
   done
 done
 if [[ $stale_caches -eq 0 ]]; then
+  caches_fresh="fresh"
   _ok "shell caches" "fresh"
 else
+  caches_fresh="stale"
   _warn "shell caches" "stale ($stale_tools) — run dot prewarm"
 fi
 
@@ -618,8 +642,22 @@ fi
 # A mise-managed 2026 dev machine routinely adds 60-90 entries (one per
 # installed tool version + per-shim path), so the warn/fail thresholds
 # reflect that baseline rather than a lean default (~40).
+#
+# The OK ceiling was 75, which contradicted the 60-90 baseline stated right
+# above it and warned on every healthy mise machine. Worse, the implied remedy
+# was backwards: those per-tool entries are what let a command resolve to the
+# real binary instead of falling through to a mise shim. Measured 2026-08-20,
+# 20 invocations of ripgrep --version:
+#
+#     via shim            2741ms   (137ms per call)
+#     direct install dir    62ms   (3.1ms per call)
+#
+# ~44x. "Pruning" those entries to satisfy a length check would trade
+# microseconds of PATH scan for ~134ms on every single tool invocation. The
+# ceiling now matches the documented baseline; >90 still warns, because past
+# that the entries are worth auditing for tools you no longer use.
 path_count=$(printf '%s' "${PATH:-}" | tr ':' '\n' | grep -c . || true)
-if [[ "$path_count" -le 75 ]]; then
+if [[ "$path_count" -le 90 ]]; then
   _ok "PATH length" "$path_count entries"
 elif [[ "$path_count" -le 120 ]]; then
   _warn "PATH length" "$path_count entries — consider pruning"
@@ -666,10 +704,18 @@ if command -v zsh >/dev/null 2>&1 && command -v timeout >/dev/null 2>&1; then
 fi
 
 if command -v hyperfine >/dev/null 2>&1; then
-  if bash "$SCRIPT_DIR/../../tests/performance/bench.sh" 2>/dev/null; then
+  if bash "$SCRIPT_DIR/../../benches/bench.sh" 2>/dev/null; then
     _ok "startup latency" "within target thresholds"
   else
-    _warn "startup latency" "threshold exceeded (run dot prewarm)"
+    # Only suggest prewarm when it could actually help. The caches were
+    # already reported fresh above in the common case, and telling someone to
+    # re-run a no-op sends them in a circle — as it did on 2026-08-20, where
+    # prewarm changed nothing because nothing was cold.
+    if [[ "${caches_fresh:-unknown}" == "fresh" ]]; then
+      _warn "startup latency" "threshold exceeded (caches already fresh — profile with 'dot benchmark')"
+    else
+      _warn "startup latency" "threshold exceeded (run dot prewarm)"
+    fi
   fi
 else
   _warn "hyperfine" "missing (benchmark skipped)"

package/scripts/diagnostics/drift-dashboard.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # =============================================================================
 # drift-dashboard.sh — Consolidated drift report.
@@ -71,7 +71,8 @@ fi
 # Class 1: chezmoi-managed drift
 # -----------------------------------------------------------------------------
 
-cm_status="$(chezmoi status 2>/dev/null || true)"
+# --exclude=always: always-run scripts are pending by design, not drift.
+cm_status="$(chezmoi status --exclude=always 2>/dev/null || true)"
 cm_count=0
 if [[ -n "$cm_status" ]]; then
   cm_count=$(printf '%s\n' "$cm_status" | wc -l | tr -d ' ')

package/scripts/diagnostics/health.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles Health Check Dashboard
 # Usage: dot health [--verbose|-v] [--json|-j] [--fix|-f] [--force|-F]
@@ -124,7 +124,7 @@ check() {
         if [[ "$use_ui" = "1" ]]; then
           ui_warn "$name" "$message"
         else
-          printf "${YELLOW}⚠${NC} %-35s ${YELLOW}WARNING${NC}"
+          printf "${YELLOW}⚠${NC} %-35s ${YELLOW}WARNING${NC}" "$name"
           [[ -n "$message" ]] && printf " ${GRAY}%s${NC}" "$message"
           printf "\n"
         fi
@@ -137,7 +137,7 @@ check() {
         if [[ "$use_ui" = "1" ]]; then
           ui_err "$name" "$message"
         else
-          printf "${RED}✗${NC} %-35s ${RED}FAILED${NC}"
+          printf "${RED}✗${NC} %-35s ${RED}FAILED${NC}" "$name"
           [[ -n "$message" ]] && printf " ${GRAY}%s${NC}" "$message"
           printf "\n"
         fi
@@ -235,7 +235,13 @@ check_dev_tools() {
 
   if has_command node; then
     local node_version
-    node_version=$(node --version 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: an assignment takes the exit
+    # status of its command substitution, so a `node` that fails to report a
+    # version aborts the entire health report mid-section — no Summary, no
+    # score, rc=1. That is exactly what happened when `node` resolved to a
+    # mise shim under a sandboxed HOME. A diagnostic tool must survive the
+    # tools it is diagnosing.
+    node_version=$(node --version 2>/dev/null || true)
     check "Node.js ($node_version)" "pass"
   else
     check "Node.js" "warn" "Not installed"
@@ -251,7 +257,10 @@ check_dev_tools() {
 
   if has_command python3; then
     local py_version
-    py_version=$(python3 --version 2>/dev/null | cut -d' ' -f2)
+    # pipefail is on, so this pipeline reports python3's failure even though
+    # `cut` succeeds — and an assignment inherits that status, aborting the
+    # report under `set -e`. Same hazard as node_version above.
+    py_version=$(python3 --version 2>/dev/null | cut -d' ' -f2 || true)
     check "Python ($py_version)" "pass"
   else
     check "Python" "warn" "Not installed"
@@ -335,7 +344,12 @@ check_security() {
 
   if has_command age; then
     check "Age encryption" "pass"
-    if [[ -f "${HOME}/.config/chezmoi/key.txt" ]]; then
+    local age_identity="${HOME}/.config/chezmoi/key.txt" configured_identity=""
+    if has_command chezmoi && has_command jq; then
+      configured_identity=$(chezmoi dump-config --format=json 2>/dev/null | jq -r '.age.identity // empty' 2>/dev/null || true)
+      [[ -z "$configured_identity" ]] || age_identity="${configured_identity/#\~/$HOME}"
+    fi
+    if [[ -f "$age_identity" ]]; then
       check "Age key configured" "pass"
     else
       check "Age key configured" "warn" "Key not found"
@@ -344,17 +358,35 @@ check_security() {
     check "Age encryption" "warn" "Not installed"
   fi
 
-  if [[ -f "${HOME}/.ssh/id_ed25519" ]] || [[ -f "${HOME}/.ssh/id_rsa" ]]; then
+  local -a ssh_keys=("$HOME/.ssh/id_ed25519" "$HOME/.ssh/id_rsa" "$HOME/.ssh/id_ed25519_sk")
+  local public_key key existing_key keys_found=false
+  for public_key in "$HOME/.ssh/"*.pub; do
+    [[ -f "$public_key" && -f "${public_key%.pub}" ]] || continue
+    key="${public_key%.pub}"
+    for existing_key in "${ssh_keys[@]}"; do
+      [[ "$existing_key" != "$key" ]] || continue 2
+    done
+    ssh_keys+=("$key")
+  done
+  for key in "${ssh_keys[@]}"; do
+    [[ ! -f "$key" ]] || keys_found=true
+  done
+  if $keys_found; then
     check "SSH keys present" "pass"
   else
     check "SSH keys present" "warn" "No keys found"
   fi
 
   # Check SSH key permissions
-  for key in "$HOME/.ssh/id_ed25519" "$HOME/.ssh/id_rsa" "$HOME/.ssh/id_ed25519_sk"; do
+  for key in "${ssh_keys[@]}"; do
     if [[ -f "$key" ]]; then
       local perms
-      perms=$(stat -c '%a' "$key" 2>/dev/null || stat -f '%Lp' "$key" 2>/dev/null)
+      # Same hazard as node_version above: if BOTH stat spellings fail (a
+      # platform with neither GNU nor BSD stat), the assignment is non-zero
+      # and `set -e` kills the report. Empty perms falls through to the
+      # "should be 600" warning, which is the right answer when the mode
+      # cannot be read.
+      perms=$(stat -c '%a' "$key" 2>/dev/null || stat -f '%Lp' "$key" 2>/dev/null || true)
       if [[ "$perms" != "600" && "$perms" != "400" ]]; then
         check "SSH key perms (${key##*/})" "warn" "mode $perms (should be 600)"
       else
@@ -440,7 +472,8 @@ check_sync_status() {
   # needs warned about via the health dashboard.
   if has_command chezmoi; then
     local status_output
-    status_output=$(chezmoi status 2>/dev/null || echo "")
+    # --exclude=always: always-run scripts are pending by design, not drift.
+    status_output=$(chezmoi status --exclude=always 2>/dev/null || echo "")
     if [[ -z "$status_output" ]]; then
       check "Chezmoi sync" "pass"
     else

package/scripts/diagnostics/history-analysis.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/diagnostics/mcp-doctor.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## MCP configuration diagnostics and hardening checks.
 ##
@@ -398,7 +398,7 @@ if command -v jq >/dev/null 2>&1; then
       {
         jq -r '.mcpServers | to_entries[]? | (.value.env // {}) | to_entries[]?.value' "$MCP_CONFIG"
         jq -r '.mcpServers | to_entries[]? | (.value.args // [])[]?' "$MCP_CONFIG"
-      } | sed -n 's/^\${\([A-Z0-9_]\+\)}$/\1/p' | sort -u
+      } | sed -n 's/^\${\([A-Z0-9_][A-Z0-9_]*\)}$/\1/p' | sort -u
     )"
     if [[ -z "$env_vars" ]]; then
       log_success "Server env placeholders" "none declared"

package/scripts/diagnostics/perf.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Shell Performance Profiling
 # Usage: dot perf [--json|-j] [--profile|-p] [--runs|-r N] [--target|-t MS]

package/scripts/diagnostics/scorecard.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles Scorecard
 # Usage: dot scorecard [--json|-j]
@@ -52,7 +52,8 @@ perf_target=$(python3 -c 'import json,sys; j=json.loads(sys.stdin.read()); print
 
 # Drift count
 if command -v chezmoi >/dev/null 2>&1; then
-  drift_count=$(chezmoi status 2>/dev/null | wc -l | tr -d ' ')
+  # --exclude=always: always-run scripts are pending by design, not drift.
+  drift_count=$(chezmoi status --exclude=always 2>/dev/null | wc -l | tr -d ' ')
 else
   drift_count=0
 fi

package/scripts/diagnostics/secret-governance.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/diagnostics/security-score.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## Security Score Assessment.
 ##

package/scripts/diagnostics/smoke-test.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Smoke tests to quickly verify toolchain health after installation/updates.
 

package/scripts/diagnostics/snapshot.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Snapshot current system/tooling state
 # Usage: dot snapshot [--baseline|-b] [--force|-f]

package/scripts/diagnostics/verify.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles post-merge verification checks
 # Runs doctor + status + diff checks and exits non-zero on issues.

package/scripts/diagnostics/verify_state.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # MIT License
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # See LICENSE file for details.
 

package/scripts/diagnostics/version-locks.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Version Locks Summary
 # Usage: dot locks

package/scripts/diagnostics/workstation-attestation.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## Workstation attestation export.
 ##
@@ -25,12 +25,23 @@ JSON_MODE=0
 WRITE_PATH=""
 FLEET_STORE=""
 FLEET_ID=""
+VERIFY=0
+VERIFY_MAX_AGE=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --json | -j)
       JSON_MODE=1
       shift
       ;;
+    --verify | -V)
+      VERIFY=1
+      shift
+      ;;
+    --max-age | -a)
+      VERIFY_MAX_AGE="${2:-}"
+      VERIFY=1
+      shift 2
+      ;;
     --write | -w)
       WRITE_PATH="${2:-}"
       shift 2
@@ -171,6 +182,20 @@ if [[ -n "$FLEET_STORE" ]]; then
   printf '%s\n' "$attestation_json" >"$fleet_timestamp_file"
 fi
 
+# Hand the evidence to the WebAssembly verifier rather than printing it.
+# The module has no access to this machine beyond the bytes on its stdin, so
+# the verdict does not depend on the tools the machine under review happens
+# to have installed.
+if [[ "$VERIFY" -eq 1 ]]; then
+  verify_args=(--verify)
+  [[ "$JSON_MODE" -eq 1 ]] && verify_args+=(--json)
+  [[ -n "$VERIFY_MAX_AGE" ]] && verify_args+=(--max-age "$VERIFY_MAX_AGE")
+  verify_status=0
+  printf '%s\n' "$attestation_json" |
+    bash "$SCRIPT_DIR/attest-verify.sh" "${verify_args[@]}" || verify_status=$?
+  exit "$verify_status"
+fi
+
 if [[ "$JSON_MODE" -eq 1 ]]; then
   printf '%s\n' "$attestation_json"
 else

package/scripts/dot/commands/agent.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Agent Mode Commands (extracted from meta.sh)
 # mode list|current|show|set|run|doctor|card|log|checkpoint|conformance
@@ -21,6 +21,55 @@ _agent_repo_root() {
   require_source_dir
 }
 
+## _agent_run_bounded <seconds> <command…> — run a command under a wall-clock
+## limit on every platform we ship to.
+##
+## `timeout` is GNU coreutils. Stock macOS has neither it nor `gtimeout`
+## (that one arrives with `brew install coreutils`), so the delegate arm's
+## former `timeout "$t" "$@"` meant the delegated command never ran at all on
+## a clean Mac — it died 127, "command not found". perl is present on both
+## macOS and the CI runners and gives us fork + alarm, which is what timeout(1)
+## does. tests/framework/assertions.sh solves the same problem the same way.
+##
+## Exit codes follow GNU timeout: 124 on expiry, 128+N when signalled,
+## otherwise the command's own status.
+_agent_run_bounded() {
+  local seconds="$1"
+  shift
+  local bin
+  bin="$(type -P timeout || true)"
+  [[ -n "$bin" ]] || bin="$(type -P gtimeout || true)"
+  if [[ -n "$bin" ]]; then
+    "$bin" "$seconds" "$@"
+    return
+  fi
+  if command -v perl >/dev/null 2>&1; then
+    perl -e '
+      my $secs = shift @ARGV;
+      my $pid  = fork();
+      die "dot: fork failed: $!\n" unless defined $pid;
+      if ($pid == 0) {
+        exec { $ARGV[0] } @ARGV;
+        exit 127;
+      }
+      my $timed_out = 0;
+      $SIG{ALRM} = sub { $timed_out = 1; kill("TERM", $pid); kill("KILL", $pid); };
+      alarm($secs);
+      my $reaped;
+      do { $reaped = waitpid($pid, 0); } while ($reaped == -1 && $!{EINTR});
+      my $status = $?;
+      alarm(0);
+      exit(124) if $timed_out;
+      exit($status & 127 ? 128 + ($status & 127) : $status >> 8);
+    ' "$seconds" "$@"
+    return
+  fi
+  # Neither available: running the command is still better than refusing to,
+  # but the lost guarantee is said out loud rather than assumed.
+  ui_warn "Delegate" "no timeout(1) or perl on PATH — running without a time limit"
+  "$@"
+}
+
 _agent_profiles_file() {
   local repo_root
   repo_root="$(_agent_repo_root)"
@@ -228,15 +277,16 @@ EOF
       checkpoint_id="$(basename "$checkpoint_file" .json)"
       ui_info "Agent mode" "$name"
       dot_agent_session_log "run_start" "$name" "running" "argv=$*" "checkpoint_id=$checkpoint_id"
-      # `if !` instead of `set +e / "$@" / set -e` — bash's errexit
-      # is automatically suspended inside a conditional, so we capture
-      # the exit code cleanly without toggling shell options.
+      # Run inside the `if` condition (errexit is suspended there) and
+      # read `$?` in the else-branch: it holds the command's own status.
+      # `if ! cmd; then exit_code=$?` reads the negation's status (0) and
+      # silently reported every failure as exit 0.
       local exit_code=0
-      if ! "$@"; then
+      if "$@"; then
+        dot_agent_session_log "run_finish" "$name" "ok" "exit_code=$exit_code" "checkpoint_id=$checkpoint_id"
+      else
         exit_code=$?
         dot_agent_session_log "run_finish" "$name" "failed" "exit_code=$exit_code" "checkpoint_id=$checkpoint_id"
-      else
-        dot_agent_session_log "run_finish" "$name" "ok" "exit_code=$exit_code" "checkpoint_id=$checkpoint_id"
       fi
       return "$exit_code"
       ;;
@@ -347,11 +397,11 @@ EOF
           _agent_apply_profile_env "$replay_profile"
           dot_agent_session_log "checkpoint_replay" "$replay_profile" "running" "checkpoint_id=$checkpoint_id"
           local exit_code=0
-          if ! "${replay_argv[@]}"; then
+          if "${replay_argv[@]}"; then
+            dot_agent_session_log "checkpoint_replay_finish" "$replay_profile" "ok" "checkpoint_id=$checkpoint_id" "exit_code=$exit_code"
+          else
             exit_code=$?
             dot_agent_session_log "checkpoint_replay_finish" "$replay_profile" "failed" "checkpoint_id=$checkpoint_id" "exit_code=$exit_code"
-          else
-            dot_agent_session_log "checkpoint_replay_finish" "$replay_profile" "ok" "checkpoint_id=$checkpoint_id" "exit_code=$exit_code"
           fi
           return "$exit_code"
           ;;
@@ -392,13 +442,13 @@ EOF
       dot_agent_session_log "delegate_start" "$delegate_profile" "running" "delegate=$delegate_name" "parent=$current_profile" "timeout=$delegate_timeout"
       ui_info "Delegating" "$delegate_name (profile: $delegate_profile, timeout: ${delegate_timeout}s)"
       local exit_code=0
-      if ! timeout "$delegate_timeout" "$@"; then
+      if _agent_run_bounded "$delegate_timeout" "$@"; then
+        dot_agent_session_log "delegate_finish" "$delegate_profile" "ok" "delegate=$delegate_name" "exit_code=$exit_code"
+        ui_ok "Delegate" "$delegate_name completed"
+      else
         exit_code=$?
         dot_agent_session_log "delegate_finish" "$delegate_profile" "failed" "delegate=$delegate_name" "exit_code=$exit_code"
         ui_err "Delegate" "$delegate_name failed (exit $exit_code)"
-      else
-        dot_agent_session_log "delegate_finish" "$delegate_profile" "ok" "delegate=$delegate_name" "exit_code=$exit_code"
-        ui_ok "Delegate" "$delegate_name completed"
       fi
       return "$exit_code"
       ;;

package/scripts/dot/commands/agents.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck shell=bash
 #
@@ -148,10 +148,18 @@ cmd_agents() {
         ui_warn "AGENTS.md" "missing — run 'dot agents render'"
         return 1
       fi
-      # Diff the bodies (header comments differ by design).
-      # `--ignore-blank-lines` so the trailing newline from the footer
-      # block doesn't false-positive as drift.
-      if diff -q --ignore-blank-lines <(_agents_body "$claude_md") <(_agents_body "$agents_md") >/dev/null 2>&1; then
+      # Compare the bodies (header comments differ by design), ignoring
+      # blank lines: the rendered file carries an extra one after its
+      # header block. This deliberately does NOT lean on
+      # `diff -q --ignore-blank-lines` — some BSD diff builds (macOS 14's,
+      # for one) short-circuit `-q` to a byte comparison and drop the
+      # ignore flags, which made `check` report drift on a tree it had
+      # just rendered. Stripping the blank lines here is implementation-
+      # independent.
+      local _claude_body _agents_body_text
+      _claude_body="$(_agents_body "$claude_md" | grep -v '^[[:space:]]*$')"
+      _agents_body_text="$(_agents_body "$agents_md" | grep -v '^[[:space:]]*$')"
+      if [[ "$_claude_body" == "$_agents_body_text" ]]; then
         ui_ok "AGENTS.md" "in sync with CLAUDE.md"
         return 0
       fi
@@ -185,9 +193,17 @@ cmd_agents() {
 -->
 
 HEADER
-        # Replace the title line so the rendered file declares its
-        # purpose, but pass everything else through unchanged.
-        _agents_body "$claude_md" | sed '1s/^# CLAUDE\.md.*/# AGENTS.md — AI Assistant Guidelines/'
+        # The title is emitted, not substituted. This used to be
+        #
+        #     _agents_body … | sed '1s/^# CLAUDE\.md.*/# AGENTS.md — …/'
+        #
+        # but _agents_body drops the H1 by design (the two files differ
+        # there), so line 1 of its output was never the CLAUDE.md title and
+        # the substitution could not fire: the rendered file carried no title
+        # at all. `check` is unaffected either way — it compares bodies with
+        # the H1 stripped from both sides.
+        printf '# AGENTS.md — AI Assistant Guidelines\n'
+        _agents_body "$claude_md"
         cat <<'FOOTER'
 
 ---