skills-public/afk-sleep-work.md

---
name: afk-sleep-work
description: >-
  Use this skill when the user indicates they will be 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 token/subscription margins (the "last breath" rule), and bypassing or driving GUI launchers.
---

# Unattended & Autonomous Execution (AFK / Sleep Work)

How to operate safely, productively, and continuously when the user steps away and delegates
broad execution authority to the agent.

When a user says they will be AFK or going to sleep, they are relinquishing the interactive
feedback loop. Every decision, recovery, tool installation, and verification gate must be
orchestrated autonomously until the goal is achieved or budget limits are reached.

---

## 1. The Autonomous Execution Contract

When working unattended, the agent assumes full responsibility for forward momentum and system
preservation. Three primary rules govern this mode:

1. **Keep Moving Forward:** Do not stop to ask clarifying questions about minor ambiguities or
   blockers that can be resolved through investigation, trial hypotheses, or alternative strategies.
2. **First, Do No Harm:** Broad authority is **not** permission to degrade the host, saturate
   resources, clobber system packages, or risk data loss.
3. **Leave a Transparent Audit Trail:** When the user returns, they must be able to inspect an
   orderly checkpoint detailing what was done, what succeeded, what failed, and where state currently sits.

---

## 2. Trap Avoidance: Loops, Timeouts & Interactive Prompts

The most common failure mode during unattended execution is getting wedged in a blocking state,
consuming time or tokens without making progress.

### 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.

- **Use built-in blocking or notification mechanisms:** Prefer CLI flags like `--wait`,
  `--no-detach`, or dedicated background task status notifications over manual polling.
- **Enforce hard timeouts:** Every long-running, external, or uncertain command must be wrapped
  in a timeout:
  ```bash
  timeout 300s my-command --batch
  ```
  If a process exceeds its expected runtime, terminate it, record the timeout, and inspect logs.

### Non-interactive flags are mandatory

Commands that pause for user confirmation (`[y/N]`) will stall indefinitely when the user is away:

- Always supply non-interactive switches: `-y`, `--yes`, `--non-interactive`, `--batch`,
  `--headless`, or environment flags like `CI=1` and `DEBIAN_FRONTEND=noninteractive`.
- Consult [`cli-tooling.md` §2](skills-public/cli-tooling.md) before invoking unfamiliar tools to ensure
  targets and arguments are explicitly declared rather than prompted.

### Bounded retries with hypothesis variation

If an automated build, test, or patch fails:
- **Do not retry the exact same failing command** hoping for a different outcome.
- Limit automated retries on any single problem to a fixed ceiling (e.g. 3 attempts).
- Each retry **must test a distinct hypothesis** (different compiler flag, altered configuration,
  corrected dependency path, or alternative implementation strategy).
- If 3 successive attempts fail, abandon that branch, record the detailed diagnostic log, and
  pivot to an alternative route or proceed to the next independent task.

---

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

Unattended access requires strict operational discipline to ensure the machine remains stable,
responsive, and intact.

### Storage & disk preservation

Running out of disk space can corrupt databases, break desktop sessions, and crash background daemons.

- **Check free space first:** Run `df -h <target_path>` before downloading large archives,
  compiling large codebases, or unpacking toolchains.
- **Never saturate drives:** Ensure at least 15–20% of disk space remains free on the root and
  working filesystems.
- **Clean intermediate artifacts:** Delete downloaded archive files (`.tar.gz`, `.zip`, `.iso`),
  temporary unpack directories, and oversized intermediate build caches once installation or
  verification is complete.
- **Log rotation and dump bounds:** Prevent automated runs from generating unbounded log files or
  gigabyte-scale core dumps.

### OS and system package integrity

- **Never mutate or override host system packages:** Do not execute blanket system package manager
  upgrades or installs (`sudo dnf install`, `sudo apt-get upgrade`, `pacman -Syu`) that replace
  host libraries, alter desktop drivers, or conflict with system-level package trees.
- **Isolate in containers or user space:**
  - Prefer dedicated build containers, chroots, or isolated environments (such as
    [`distrobox-buildbox-dev.md`](skills-private/distrobox-buildbox-dev.md), Docker, or Podman) for
    compilers, toolchains, and experimental packages.
  - For user-level binaries, install into user-scoped paths (`~/.local/bin/`, `~/.local/share/`,
    or project-local virtual environments).
  - Never run arbitrary third-party build scripts with elevated root privileges unless explicitly
    demanded by the architecture and verified safe.

### Process and lifecycle safety

- **Strictly prohibited operations:**
  - Never invoke `shutdown`, `reboot`, `systemctl poweroff`, or `init 0/6`.
  - Never kill the host desktop session, display server (`wayland`, `xorg`), or user window manager.
  - Never issue broad `pkill` or `killall` commands with generic names (e.g. `pkill python` or
    `killall node`) that might terminate the agent itself, IDE sidecars, or unrelated user processes.
  - Always target specific PIDs or match full command lines (`pkill -f ...`).

### CPU, memory, and bandwidth etiquette

- **Do not saturate all CPU cores:** When invoking multi-threaded builds (`make`, `ninja`, `cargo`),
  cap jobs to `$(nproc --ignore=2)` or use `nice -n 10` to avoid starving interactive desktop
  responsiveness or audio subsystems.
- **Monitor memory footprints:** For heavy memory operations (e.g. large reverse engineering suites,
  AST parsing, heavy link steps), monitor RAM with `free -m` and kill runaway tasks before triggering
  the kernel OOM killer.

---

## 4. Tool & Dependency Provisioning in Isolation

Autonomous work often demands tools not yet present on the system (e.g. decompilers, disassemblers,
symbol analyzers, cross-compilers, or profiling utilities).

### Check existence before fetching

Always verify if a tool or functional equivalent is already available in `$PATH`, in an existing
container, or in user directories before attempting to download:

```bash
command -v <tool> || which <tool>
```

### Preferred provisioning hierarchy

When a missing utility or dependency is required:

1. **Local Project / Toolchains:** Look for existing scripts or submodule toolchains inside the repo.
2. **Isolated Build Containers:** Run or install the tool within a development container or
   Distrobox instance, keeping the host clean.
3. **Self-Contained User-Space Binaries:** Download official prebuilt standalone binaries, AppImages,
   or portable zip releases into `~/.local/bin/` or a project scratch folder.
4. **Isolated Package Managers:** Use language-specific or user-space package managers (`cargo install`,
   `pip install --user`, `npm install --no-save`, `go install`) scoped to non-root directories.

### Headless & scriptable mode over GUI

When using heavyweight tools that typically feature GUIs (such as Ghidra, IDA, Wireshark, or
debuggers):

- **Always prioritize headless/CLI mode:** Use headless batch scripts, CLI entrypoints, or
  Python/Java/Lua automation APIs rather than starting graphical interfaces.
  - *Example (Ghidra):* Run `analyzeHeadless <project_dir> <project_name> -import <binary> -postScript <script.py>`
    rather than launching the Swing GUI.
  - *Example (Network/Packets):* Use `tshark` or `tcpdump` instead of launching GUI Wireshark.
  - *Example (Debugging):* Run `gdb -batch -ex ...` or `lldb --batch -o ...`.

---

## 5. Launchers & GUI Automation: Bypassing vs. Driving

Complex applications, game engines, and test suites often wrap their executables behind splash
launchers, web views, or login modals. When running unattended, handle them systematically.

```
┌────────────────────────────────────────────────────────┐
│ 1. Direct Executable Bypass (Preferred)                │
│    Inspect process args, run child binary directly     │
└───────────────────────────┬────────────────────────────┘
                            │ (if blocked by DRM / IPC)
┌───────────────────────────▼────────────────────────────┐
│ 2. Command-Line Arguments & Flags                      │
│    Search for -nosplash, -nolauncher, --skip-intro     │
└───────────────────────────┬────────────────────────────┘
                            │ (if GUI invocation mandatory)
┌───────────────────────────▼────────────────────────────┐
│ 3. Autonomous GUI Driving                              │
│    Locate window, simulate inputs, verify state change │
└────────────────────────────────────────────────────────┘
```

### Hierarchy of execution

1. **Direct Executable Bypass (Highest Priority):**
   Launchers are usually thin wrappers around the real core engine or binary.
   - Run the launcher once or inspect its script / configuration files to identify the real child
     binary and its working directory.
   - Inspect active processes (`ps aux | grep -i <app>` or `wmic process` under Wine/Windows) to
     extract the exact command line and parameters passed from the launcher to the target process.
   - Execute the target binary directly with those extracted parameters, bypassing the launcher UI
     completely.

2. **Command-Line & Config Flags:**
   If the launcher must be invoked, look for flags that suppress interactive prompts:
   - Common bypass switches: `-nosplash`, `-nolauncher`, `-autostart`, `-batch`, `-silent`, `--skip-login`.
   - Configuration files: Check configuration `.ini`, `.json`, or `.xml` files to toggle
     `SkipLauncher=true` or set auto-connect / auto-load options.

3. **Driving the GUI (Fallback):**
   If the launcher cannot be bypassed and requires a click or keyboard event to proceed:
   - Identify the window using available window management or GUI automation tools
     (e.g. `xdotool`, `ydotool`, or desktop MCP tools).
   - Capture a screenshot or window dump to verify geometry and interactive button states.
   - Dispatch the required input sequence (e.g. Enter, Space, or target coordinate click).
   - **Immediately verify state transition:** Confirm the launcher window closes or the child
     process spawns. Never assume input succeeded without checking process lists or window titles.
   - Protect with a hard timeout so that an unexpected modal dialog does not block execution forever.

---

## 6. Token & Subscription Exhaustion (The "Last Breath" Rule)

In unattended sessions, the execution lifecycle is bounded by context window size, agent token
budgets, subscription quotas, or harness timeouts. How the session winds down determines whether
the run is a success or leaves a broken system.

### Watch for approaching limits

Track execution consumption and context density where possible:
- If context length grows high or the harness signals approaching token/turn caps, prioritize
  winding down over starting new initiatives.
- If rate limits, credit caps, or subscription tier resets are anticipated, prepare state so that
  execution can pause cleanly and recover without corruption.

### Never start fragile tasks in your "last breath"

> [!CAUTION]
> **The "Last Breath" Trap:** Never initiate an open-ended, non-atomic, or high-risk mutating
> operation when token budget, context window, or subscription quota are nearly exhausted.

Rushing into a complex task with only a few turns or tokens remaining guarantees failure. If the
harness cuts execution off mid-flight — or freezes the agent until quota resets hours later —
unfinished work leaves the environment in a broken, unusable state:
- **Corrupted source trees:** Half-applied multi-file refactors that leave syntax errors and broken builds.
- **Dangling locks:** Incomplete package installs holding `/var/lib/dpkg/lock`, active git index
  locks (`.git/index.lock`), or held database transactions.
- **Uncommitted state:** Unfinished rebases, stashes, or uncommitted modifications that confuse
  subsequent runs or the user.
- **Zombie processes:** Orphaned background build daemons, open sockets, or runaway test loops
  consuming host memory.

### The Controlled Landing protocol

When budget, tokens, or turns drop below a comfortable margin (or when an operation cannot be
guaranteed to finish and verify within the remaining budget):

1. **Stop scope expansion:** Refuse new goals, refactors, or dependency upgrades.
2. **Finish or roll back atomic units:** Complete the immediate atomic file edit or roll it back
   cleanly (`git checkout -- <file>`) so the repository remains in a compiling, testable state.
3. **Terminate ephemeral processes:** Kill all background test runners, scratch servers, and
   temporary debuggers.
4. **Run verification gates:** Confirm `git status` is clean or staged cleanly, and the build passes.
5. **Commit atomic progress:** Commit completed, verified units with conventional commit messages so
   progress is never lost if the session terminates abruptly.
6. **Write the recovery checkpoint:** Explicitly document the exact resume instructions, active
   hypotheses, and next planned action in the status artifact so either the user or the next agent
   turn can resume seamlessly.

---

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

Because the user is not present to monitor intermediate chatter, keep a consolidated record of
progress.

### Write a live status checkpoint

Maintain a dedicated status file (e.g. `PROGRESS.md`, `AFK_WORK_LOG.md`, or a persistent artifact)
updated after every major milestone. The document should contain:

| Section | Contents |
| :--- | :--- |
| **Objective** | The original task and current operational phase. |
| **Completed Work** | Bulleted list of concrete accomplishments (code written, tests passing, tools configured). |
| **Current State** | Active branch, git commit hash, build status, running daemons or services. |
| **Findings & Discoveries** | Key technical observations, reversed structs, discovered bugs, or API quirks. |
| **Obstacles & Fallbacks** | Blockers encountered, strategies that failed (with brief reasons), and how the agent pivoted. |
| **Harness / Budget State** | Token/quota state, whether work halted due to task completion or approaching budget limits. |
| **Immediate Next Steps** | Exact command line or file target where the next session should pick up. |

### Clean exit on budget exhaustion

When tokens, context, or scheduled runtime run out:
- Ensure the controlled landing steps above have been executed.
- Output a concise, unambiguous final summary pointing directly to the written checkpoint so the
  user has immediate clarity upon waking up or returning.