bash-debugging-cleanup

# Debugging and cleanup Open this when a scheduler is silent, fires twice, exits early, or must be retired. Diagnose in order; do not assume that a successful scheduler exit means that the work or wake reached the agent. ## Silent scheduled work 1. **Did the scheduler fire?** macOS: `launchctl list <label>` and inspect `PID`/`LastExitStatus`; Linux: `systemctl --user list-timers`; cron: inspect `/var/log/cron` or `journalctl -u cron` for `CMD`. Check unit syntax (`plutil -lint` or `systemctl --user status`), loaded/disabled state, sleep catch-up behavior, and clock time. 2. **Did the script run?** Read its own append-only log, not only scheduler stdout/stderr. A missing `[fire]` means an early launch failure; a `[fire]` without completion means an in-script failure. Keep `set -euo pipefail` and log the command boundary that failed. 3. **Did work land?** Compare the script's audit evidence with the expected artifact/commit/message. A logged success with no artifact is script logic, not a scheduler mystery. 4. **Did the agent see the wake?** For mailbox work, inspect human `mailbox/outbox/<uuid>`, then `mailbox/sent/<uuid>`, then the recipient's `mailbox/inbox/<uuid>`. Validate malformed JSON and confirm the recipient. A queued mail waits for the next turn; use the scheduler reference's `.refresh` rule only when prompt pickup is required. ## Retire without a janitor race First obtain explicit authority for stopping/removing the named scheduler and review a dry-run. Then: 1. Unload the unit (`launchctl unload <plist>` or `systemctl --user disable --now <timer>`), and verify it is gone. 2. Only then remove the unit and script; archive logs if history matters. 3. Record the unit name and retained evidence. Never delete the script first, remove `.agent.lock`, or launch a parallel relaunch: the kernel owns its flock and refresh watcher. On macOS, a scheduler may reap descendants when its process exits; read the scheduled-work process-tree warning before intentionally launching a long-lived child. ## Shell footprint Shell may create scripts, logs, downloads, virtualenvs, scheduler units, and build artifacts. Retain artifacts by default. Cleanup is command-specific: show a dry-run and obtain explicit human authorization before destructive removal. For inspection, call `psyche(action="skills", input={})`, then follow `skills-manual` to `reference/cleanup-footprint-contract.md` and its shared footprint recipe. Combine it with this task's selected paths in one script. Inspection writes nothing. If the human selected an audit, append to `logs/cleanup.jsonl` and record retired scheduler units.