skills-public/afk-sleep-work.md

---
name: afk-sleep-work
description: >-
  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](skills-public/code-languages/bash.md)).
> 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](skills-public/cli-tooling.md)).
- **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`](skills-private/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.