Reliable non-interactive shell environments: practice drills

Six exercises diagnose missing tools through non-interactive zsh startup, environment markers, PATH ordering, a bootstrap recheck, configuration placement, and function-versus-executable classification.

These exercises practice diagnosing agent shell visibility without turning the session into a full dotfiles audit.

Exercise 1: Write A Missing Tool Prompt

Write a prompt that asks an agent to diagnose one missing tool.

Template:

Codex cannot find `<tool>`, but it works in my terminal.

Inspect the non-interactive zsh startup path. Check `zsh -lc`, `ZDOTDIR`,
the agent-safe bootstrap, PATH order, and where the tool is installed. Do not
print secrets or full environment output. Tell me which file should change and
how to confirm it worked.

Exercise 2: Agent Env Snapshot

Run the confirmation shape for your machine:

zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'

Write:

# Agent Env Snapshot

- shell shape:
- ZDOTDIR:
- marker:
- tools found:
- tools missing:
- next action:

Exercise 3: Number PATH

zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,30p"'

Write:

# PATH Notes

- first project/toolchain path:
- package manager path:
- language runtime path:
- Homebrew path:
- suspicious entries:
- what should move:

Exercise 4: Clean-Shell Check

env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'

Answer:

# Clean-Shell Check

- Did the marker become set again?
- Did required tools resolve?
- What changed compared to the normal check?
- What does that imply?

Exercise 5: Place The Fix

For each case, choose the right home:

Case File Or Form
persistent PATH assembly for all shells
machine-local private path
prompt theme
keybinding
reusable command needed outside zsh
rich helper function for interactive work
safe agent bootstrap

Options:

~/.config/zsh/conf.d/00-path.zsh
~/.config/zsh/local.zsh
~/.config/zsh/codex-env.zsh
~/.config/zsh/.zshrc
executable wrapper on PATH
Section 3 zsh DSL

Exercise 6: Function Or Executable

Run:

zsh -lc 'for name in bun packx funclist fix agent_chain xfl; do echo "--- $name ---"; command -v "$name" 2>/dev/null || echo "command -v: missing"; whence -w "$name" 2>/dev/null || echo "whence: missing"; done'

Classify:

# Function Versus Executable

| name | executable / function / missing | Section 2 or Section 3? | why |
| --- | --- | --- | --- |
| bun | | | |
| packx | | | |
| funclist | | | |
| fix | | | |
| agent_chain | | | |
| xfl | | | |

Source references