Files & workspace

Long-task guard

Timeouts, logged output, checkpoints and a way out for anything that might hang.

Free Free to read and free to ask for by email.

Background

One line: turn "stuck" into "observable, interruptible, resumable". There are only four root causes of hangs and stalls — commands with no boundary (never return), output with no budget (blows up the context), state with no persistence (lost, then redone), failures with no stop-loss (the same action retried over and over). This skill closes each one.

Why it is built this way

Four things make work stall: a command with no boundary, output with no budget, state with no persistence, a failure with no stop-loss. Each one gets a script in front of it, and three of them run in the thirty seconds before work starts: guard.py pre-checks the command, budget.py measures what is about to be read, checkpoint.py init writes the goal. A BLOCK means the command gets rewritten before anything starts.

pulse.py owns the exit code vocabulary: 0 success, 124 total timeout, 125 idle timeout, and 125 usually means something is waiting on stdin. That is why the rule says read the log tail first and do not rerun. Output is tiered L0 to L2, with a single tool echo capped at 8 KB or 200 lines, because the full log belongs in work/logs/ on disk and never in the conversation.

Where it bites

• A timeout read as a failure Exit code 124 means the command was cut off at the time limit, and 125 means nothing came out for the idle window. Treated as an ordinary failure, both invite an identical rerun. The skill says read the log tail on 124 or 125, decide whether it is slow or dead, and set --timeout to twice the estimate.
• npm install with no boundary A command with no timeout and no log cannot say whether it is working or waiting for a key. The first hard rule refuses to start without a timeout, a log on disk and a liveness criterion. pulse.py supplies the timeout, work/logs/ takes the file, and wait-port or probe answers whether it is up.
• Output that ate the session One grep with several hundred matching lines pasted whole leaves a context that is mostly noise and replies that arrive truncated. The L1 cap is 120 lines with five lines of context, search results stop at 50, and anything larger goes to a file with only the path left in the conversation.
• The fourth identical retry The same command tried a fourth time fails the same way and burns another round. The three-strikes rule stops at three and forces one of three moves: change level to reading logs or source, shrink to a minimal reproduction, or stop and state what is missing. The choice goes into work/STATE.md.

Inside this skill

1. When it applies
2. Three hard rules
3. The 30 seconds before you start (three commands)
4. 1. Long commands: always go through pulse
5. 2. Long-running and interactive commands: recognise and rewrite
6. 3. Output budget: L0 / L1 / L2
7. 4. Three-strikes rule (anti-infinite-loop)
8. 5. Stall detection and escape
9. 6. Checkpoint / resume protocol
10. 7. Concurrency and subagents
11. 8. Wrap-up check (5 items, missing one means not done)
12. 9. Prohibited list
13. Companion files

The outline is the skill file's own headings, in the order it uses them.

When to use it

Any task that may run longer than 10 seconds, produce more than one screen of output, or need several rounds to push forward must pass this guard first: put timeouts and on-disk logs on commands, give output a quantified budget, write checkpoint files for progress, and provide stall detection and an escape path. Use when the task involves build/test/install/render/scrape, starting a service or GUI, large files or big logs or big diffs, a session that got slow or tool output that is being truncated, the same error repeating, or a long task that may be interrupted or needs to be handed to another session.

How to use it

1. Ask for the file by email — it is a single SKILL.md.
2. Put it in the skills folder your agent reads, in a directory named runtime-guard.
3. Start a message with the trigger from the description, or name the skill directly.