skills-public/afk-sleep-work.md

name, description

name	description
afk-sleep-work	Use this skill when the user is away, AFK, or sleeping, grants broad autonomous execution authority, asks the agent to work continuously until tokens or objectives are exhausted, or delegates multi-phase tasks requiring unattended orchestration, safe tool provisioning, avoiding polling traps, respecting budget margins (the "last breath" rule), and bypassing or driving GUI launchers.

Unattended & Autonomous Execution (AFK / Sleep Work)

When working unattended, the interactive loop is gone. Every decision, recovery, tool provisioning, and verification step must proceed autonomously without risking host stability or leaving broken state.

---

1. Autonomous Execution Contract

1. Keep Moving Forward: Do not stop for minor ambiguities. Investigate, formulate hypotheses, test, and pivot independently.
2. First, Do No Harm: Broad authority is never permission to fill disks, clobber system packages, reboot, or risk data loss.
3. Leave a Transparent Audit Trail: Maintain an orderly checkpoint detailing completed work, failures, state, and exact next steps.

---

2. Trap Avoidance: Loops, Timeouts & Interactive Prompts

The primary failure mode of unattended runs is wedging on a blocking command.

Never write polling wait loops

Caution

Strictly forbidden: Never run while, until, or sleep polling loops in shell commands (see code-languages/bash.md §3). An unattended loop that never satisfies its exit condition hangs the session indefinitely.

• Tool-native blocking & harness background tasks: Prefer flags like --wait, --no-detach, or dispatch long-running jobs as harness background tasks/daemons (with reactive completion notifications) so the synchronous execution loop never gets wedged.
• Enforce task-scaled timeouts: Never run unbounded commands. Scale timeouts deliberately based on estimated task duration (e.g. timeout 30s for quick checks, timeout 180s for tests, timeout 15m for large builds) to prevent infinite hangs on deadlocks or network stalls.
• Mandatory non-interactive flags: Supply -y, --yes, --batch, --headless, CI=1, or DEBIAN_FRONTEND=noninteractive. Never let a tool prompt [y/N] (see cli-tooling.md §2).
• Bounded retries with hypothesis variation: Never rerun the same failing command unchanged. Cap retries at 3 attempts; each must test a distinct hypothesis (flags, config, path, or alternative strategy). If all fail, record diagnostics and pivot.

---

3. Host Safety & Resource Budgets ("Do No Harm")

• Storage & Disk: Check df -h <path> before large fetches or builds. Keep ≥15–20% disk headroom. Clean up downloaded archives (.tar.gz, .zip, .iso), temp build trees, and intermediate dumps.
• OS & Package Integrity: Never run blanket host package upgrades or installs (sudo dnf, sudo apt, pacman -Syu). Isolate toolchains inside containers (e.g. distrobox-buildbox-dev.md, Docker) or user-space paths (~/.local/bin/, venvs).
• Process Safety: Never execute shutdown, reboot, or kill display servers (wayland, xorg). Never issue broad pkill python or killall node that can kill the agent or IDE. Target specific PIDs or match full paths.
• CPU & Memory: Cap multi-threaded jobs (-j$(nproc --ignore=2)), nice -n 10 heavy builds, and monitor free -m to prevent kernel OOM panics.

---

4. Tool Provisioning: Containerized & Headless First

1. Verify existence first: Run command -v <tool> before downloading.
2. Provision in isolation: Prefer existing repo toolchains > build containers (Distrobox/Docker) > standalone binaries (~/.local/bin/) > user-scoped package managers (cargo install, pip install --user).
3. Headless / CLI over GUI: Never launch heavy graphical interfaces when headless/batch modes exist:
   • Ghidra: analyzeHeadless <proj_dir> <proj_name> -import <bin> -postScript <script.py>
   • Packets: tshark / tcpdump instead of GUI Wireshark
   • Debuggers: gdb -batch -ex ... or lldb --batch -o ...

---

5. Launchers & GUI Automation: Bypass vs. Drive

When targets are shielded by splash launchers, web wrappers, or login dialogs:

Priority	Strategy	Action
1. Direct Bypass (Best)	Run child binary directly	Inspect ps aux or wrapper configs while the launcher runs to extract child binary path and arguments, then execute it directly.
2. CLI / Config Flags	Suppress launcher UI	Pass switches like -nosplash, -nolauncher, -batch, --skip-intro, or set SkipLauncher=true in .ini/.json configs.
3. GUI Automation (Fallback)	Drive the window	Target window non-interactively (wmctrl -lp, xdotool search --name <name>, Wayland tree, or desktop MCP), capture screenshot/dump, send keys/clicks, and verify state change with a timeout guard.

Warning

Beware mouse-click traps in window utilities: Never run xwininfo, xprop, xdotool selectwindow, or ImageMagick import without explicit window IDs or query flags (-root, -name, -id). Without them, these tools pause and wait indefinitely for the user to click a window, hanging unattended execution instantly.

---

6. Budget Exhaustion, Runaway Logs & The "Last Breath" Rule

In unattended sessions, context window, token budgets, or subscription quotas will eventually exhaust.

Caution

The "Last Breath" Trap: Never initiate an open-ended, non-atomic, or high-risk mutating operation when tokens, context, or quota are nearly depleted.

Rushing into a complex task on a thin margin guarantees failure if the harness terminates or pauses execution mid-flight:

• Corrupted source trees: Half-applied multi-file refactors leaving syntax errors and broken builds.
• Dangling locks: Incomplete package or git locks (.git/index.lock, /var/lib/dpkg/lock).
• Uncommitted state: Half-finished rebases, stashes, or uncommitted edits.
• Zombie processes & runaway logs: Background daemons, watchers, or detached tasks spewing debug output into unrotated log files, silently filling the disk while the agent is paused or waiting for quota.

The Controlled Landing protocol

When remaining budget or context drops below a safe margin:

1. Halt scope expansion: Do not start new goals or dependencies.
2. Finish or roll back atomic edits: Leave the repo in a compiling, testable state (git checkout -- <file> if incomplete).
3. Kill ephemeral processes & log streams: Terminate background test runners, servers, watchers, and tasks redirecting output to unrotated files.
4. Run verification gates: Verify git status and run quick build/lint checks.
5. Commit atomic progress: Save clean progress with conventional commits.
6. Write the recovery checkpoint: Update the status log before the session halts.

---

7. Checkpointing & The "Wake-Up" Audit Trail

Maintain a persistent status file (PROGRESS.md or session artifact) updated at each milestone:

Section	Contents
Objective	Target goal and current operational phase.
Completed Work	Bulleted list of verified accomplishments (code, passing tests, tools configured).
Current State	Branch, commit hash, build status, active containers or services.
Findings & Discoveries	Key technical observations, reversed structs, or API quirks.
Obstacles & Fallbacks	Failed attempts with concise explanations and how you pivoted.
Budget / Harness State	Token/quota status; whether stopped by task completion or budget limits.
Immediate Next Steps	Exact command line or target file for the next session to resume seamlessly.

Conclude with a single clear summary pointing the returning user directly to this checkpoint.