completions/tailscale.fish

@@ -228,16 +228,15 @@ function __tailscale_prepare_completions
     return 0
 end
 
-# Since Fish completions are only loaded once the user triggers them, we trigger them ourselves
+# REMOVED (2026-09-07): Cobra's self-priming block —
-# so we can properly delete any completions provided by another script.
+#   if type -q "tailscale"; complete --do-complete "tailscale " >/dev/null 2>&1; end
-# Only do this if the program can be found, or else fish may print some errors; besides,
+# It existed to force any pre-existing tailscale completions to load so the
-# the existing completions will only be loaded if the program can be found.
+# `complete -c tailscale -e` below could erase them. From completions/ it has
-if type -q "tailscale"
+# no job: fish autoloads only the FIRST match on $fish_complete_path, and
-    # The space after the program name is essential to trigger completion for the program
+# $__fish_config_dir/completions precedes /usr/share/fish/vendor_completions.d,
-    # and not completion of the program name itself.
+# so the vendor file is never sourced and there is nothing to erase. It also
-    # Also, we use '> /dev/null 2>&1' since '&>' is not supported in older versions of fish.
+# executed the tailscale binary at startup. Verified: completion output is
-    complete --do-complete "tailscale " > /dev/null 2>&1
+# byte-identical with and without it. See AGENTS/specs/2026-09-07-startup-latency-design.md D2.
-end
 
 # Remove any pre-existing completions for the program since we will be handling all of them.
 complete -c tailscale -e

conf.d/abbr.fish

@@ -12,6 +12,9 @@
 #   site abbr-integrations: integrations/terminal-abbrs
 #   site abbr-overrides: overrides/key-bindings
 
+# Abbreviations only expand in the line editor; a script can never use one.
+status is-interactive; or return
+
 # Neovim
 # @category Editors
 # @desc nvim

conf.d/auto-pull.fish

@@ -13,6 +13,11 @@
 #
 # Manage the registry with: auto-pull add / remove / list / status
 
+# Registers an --on-variable PWD handler that backgrounds a git fetch. In a
+# script that cd's, that is both wasted work and AGENTS.md Task #4's
+# credential-prompt hazard fired from a background job.
+status is-interactive; or return
+
 # C2 guard: when auto-execution is disabled, do not register the handler.
 __fish_config_op_enabled (status basename); or exit
 

conf.d/bash_expands.fish

@@ -7,6 +7,10 @@
 # Provides bash-style history expansion functions for abbreviations.
 # These functions are gated by the C3 overrides switch.
 
+# The six expand_* functions are reachable only through abbr --function
+# (conf.d/abbr.fish:677-697), i.e. only during interactive expansion.
+status is-interactive; or return
+
 # Execute expand_bang_all
 function expand_bang_all --description 'Execute expand_bang_all'
     # Opinionated guard (C3): no expansion when overrides are disabled.

conf.d/key_bindings.fish

@@ -47,6 +47,10 @@
 # This allows for rapid-fire math without leaving the current shell.
 # ──────────────────────────────────────────────────────────────────────
 
+# Defines only fish_user_key_bindings, which fish calls from the interactive
+# reader and nowhere else.
+status is-interactive; or return
+
 function fish_user_key_bindings
 
     # Custom key chords are opinionated (C3 overrides); skip them entirely

conf.d/logging-events.fish

@@ -13,6 +13,12 @@
 # solely in functions/ are never registered and their --on-variable triggers
 # never fire.
 
+# Calls __fish_config_sync_logging at every shell start, which mkdir+touches
+# the C5 sentinel on disk. Its only consumers — the Kitty watcher and the
+# paru/yay wrappers — are interactive-context; every interactive shell still
+# refreshes it.
+status is-interactive; or return
+
 function __fish_config_logging_changed --on-variable __fish_config_op_logging \
     --description 'C5 event handler: sync logging state when __fish_config_op_logging changes'
     __fish_config_sync_logging

conf.d/paru-wrapper.fish

@@ -10,6 +10,10 @@
 #   site paru-autoexec: autoexec/pkg-wrappers
 #   site paru-logging: logging/pkg-logs
 
+# Defines nothing; its only effect is generating ~/.local/bin/paru, an
+# idempotent write every interactive session already performs.
+status is-interactive; or return
+
 # Auto-generating a wrapper in ~/.local/bin is opinionated (C2 auto-exec).
 # Wrapper generation is also gated by C5 (Logging & Capture).
 __fish_config_op_enabled (status basename) paru-autoexec; or return

conf.d/starship.fish

@@ -9,6 +9,10 @@
 # Without starship, fish's built-in prompt already emits OSC 133;A
 # on the prompt line itself, so no wrapper is needed.
 
+# Defines fish_prompt; no script renders a prompt. Checked before the
+# op-guard so the builtin short-circuits ahead of three function autoloads.
+status is-interactive; or return
+
 # Replacing the prompt is opinionated (C3 overrides)
 __fish_config_op_enabled (status basename); or return
 

conf.d/theme.fish

@@ -20,6 +20,11 @@ if not __fish_config_op_enabled (status basename)
     return
 end
 
+# Below the cleanup block on purpose: that branch erases a stale universal
+# FZF_DEFAULT_OPTS and must keep running wherever it runs today. Everything
+# past here is fish_color_* for the syntax highlighter, interactive-only.
+status is-interactive; or return
+
 #   ────────────────────── Syntax highlighting colors ──────────────────────
 set --global fish_color_autosuggestion 6c7086
 set --global fish_color_cancel f38ba8

conf.d/wakatime.fish

@@ -9,6 +9,10 @@
 #   site wakatime-autoexec: autoexec/telemetry
 #   site wakatime-hook: integrations/notifications
 
+# Registers a fish_postexec handler; that event is emitted only by the
+# interactive reader, so the handler is dead weight in a script.
+status is-interactive; or return
+
 # Local modification: opinionated guard (AGENTS.md Task #3). WakaTime
 # reporting is classified under both C2 auto-execution and C4 integrations;
 # disabling either category skips registering the hook.

conf.d/yay-wrapper.fish

@@ -10,6 +10,10 @@
 #   site yay-autoexec: autoexec/pkg-wrappers
 #   site yay-logging: logging/pkg-logs
 
+# Defines nothing; its only effect is generating ~/.local/bin/yay, an
+# idempotent write every interactive session already performs.
+status is-interactive; or return
+
 # Auto-generating a wrapper in ~/.local/bin is opinionated (C2 auto-exec).
 # Wrapper generation is also gated by C5 (Logging & Capture).
 __fish_config_op_enabled (status basename) yay-autoexec; or return

docs/fish-config.md

@@ -46,7 +46,6 @@ The configuration uses a structured file tree:
     ├── conf.d/
     │   ├── abbr.fish               All abbreviations
     │   ├── autopair.fish           Auto-pair brackets and quotes
-    │   ├── cheat.fish              cheat.sh tab completions
     │   ├── done.fish               Desktop notifications for long commands
     │   ├── first_run.fish          One-time init: Fisher bootstrap, theme
     │   ├── key_bindings.fish       Custom key bindings and Vi mode
@@ -58,14 +57,13 @@ The configuration uses a structured file tree:
     │   ├── zellij-logging.fish     C5 fish_exit handler for zellij
     │   ├── sponge_privacy.fish     Sponge privacy patterns
     │   ├── starship.fish           fish_prompt shell-integration markers
-    │   ├── tailscale.fish          Tailscale CLI tab completions
     │   ├── theme.fish              Catppuccin syntax highlight colors
     │   ├── tricks.fish             PATH, bang-bang helpers, bat man pages
     │   ├── wakatime.fish           WakaTime shell hook
     │   ├── yay-wrapper.fish        Auto-generates yay logging wrapper
     │   └── zoxide.fish             Zoxide z/zi integration; overrides cd
     ├── functions/                  Custom functions, one per file
-    ├── completions/                Tab completion scripts
+    ├── completions/                Tab completion scripts, autoloaded on demand
     ├── integrations/
     │   └── fzf.fish                FZF Catppuccin theme and key bindings
     ├── scripts/
@@ -245,7 +243,8 @@ Every shell command is reported to WakaTime for time-tracking. Set
 
 ### Tailscale
 
-Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`.
+Full tab completion for the `tailscale` CLI is provided via
+`completions/tailscale.fish`, autoloaded on the first `tailscale<TAB>`.
 
 ### Done Notifications
 

docs/manual/01-configuration-variables.md

@@ -118,7 +118,8 @@ Every shell command is reported to WakaTime for time-tracking. Set
 
 ### Tailscale
 
-Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`.
+Full tab completion for the `tailscale` CLI is provided via
+`completions/tailscale.fish`, autoloaded on the first `tailscale<TAB>`.
 
 ### Done Notifications
 

docs/manual/index.md

@@ -35,7 +35,6 @@ The configuration uses a structured file tree:
     ├── conf.d/
     │   ├── abbr.fish               All abbreviations
     │   ├── autopair.fish           Auto-pair brackets and quotes
-    │   ├── cheat.fish              cheat.sh tab completions
     │   ├── done.fish               Desktop notifications for long commands
     │   ├── first_run.fish          One-time init: Fisher bootstrap, theme
     │   ├── key_bindings.fish       Custom key bindings and Vi mode
@@ -47,14 +46,13 @@ The configuration uses a structured file tree:
     │   ├── zellij-logging.fish     C5 fish_exit handler for zellij
     │   ├── sponge_privacy.fish     Sponge privacy patterns
     │   ├── starship.fish           fish_prompt shell-integration markers
-    │   ├── tailscale.fish          Tailscale CLI tab completions
     │   ├── theme.fish              Catppuccin syntax highlight colors
     │   ├── tricks.fish             PATH, bang-bang helpers, bat man pages
     │   ├── wakatime.fish           WakaTime shell hook
     │   ├── yay-wrapper.fish        Auto-generates yay logging wrapper
     │   └── zoxide.fish             Zoxide z/zi integration; overrides cd
     ├── functions/                  Custom functions, one per file
-    ├── completions/                Tab completion scripts
+    ├── completions/                Tab completion scripts, autoloaded on demand
     ├── integrations/
     │   └── fzf.fish                FZF Catppuccin theme and key bindings
     ├── scripts/

tests/test-session.fish

@@ -60,3 +60,28 @@ set -l got (_agents_vault_dir)
 set -e __fish_agent_vault_dir
 test (count $saved) -gt 0; and set -g __fish_agent_vault_dir $saved
 check "vault dir honors the override" /tmp/vault-override-check "$got"
+
+section "session: conf.d guards are lazy in non-interactive scripts"
+
+# A non-interactive shell must not load interactive-only conf.d work. The
+# child inherits XDG_CONFIG_HOME from this sandboxed session, so it loads
+# the same config under test. Each exit code names one regression.
+#
+# Assertion 5 (tailscale) is vacuously true where tailscale is not
+# installed: conf.d/tailscale.fish returned early on `type -q tailscale`
+# before this change, and completions/tailscale.fish does the same, so the
+# function is absent either way. The test still cannot fail wrongly there
+# -- it just stops proving anything about that one file. A positive
+# "completions still work" check would need the binary present and would
+# make the suite machine-dependent, so it stays out.
+fish -c '
+    abbr -q n; and exit 1
+    functions -q fish_user_key_bindings; and exit 2
+    functions -q expand_bang_all; and exit 3
+    functions -q __fish_config_logging_changed; and exit 4
+    functions -q __tailscale_perform_completion; and exit 5
+    exit 0'
+check "conf.d guards stay out of non-interactive scripts" 0 $status
+
+# Positive counterpart to the assertion above: the guard must not over-fire.
+check "fish_user_key_bindings still defined in-session" true (functions -q fish_user_key_bindings; and echo true; or echo false)