Close Agent Runs Cleanly with ap-janitor

Where this fits

When your agent has finished a long task, it's often unclear whether it truly completed or just stopped after producing files. You find leftover scratch files, no clear completion marker, and no safe way to tell an orchestrator to rerun. ap-janitor solves that by acting as the terminal leaf in an Autoprompt run: it verifies the three-file governance state and evidence, writes a DONE sentinel atomically, and removes only scratch artifacts. This gives you a trustworthy "finished" signal without risking substantive work.

Why agents benefit

• Atomic sentinel write means a DONE marker is never visible half-written, so orchestrators won't misinterpret a failed write as completion.
• Validation-before-cleanup prevents the agent from deleting evidence or governance files when the run didn't actually satisfy the contract.
• Scope-limited cleanup targets only scratch artifacts, not user data or generated deliverables.
• The activation contract blocks nested Autoprompt runs and requires a valid RUN-NONCE, reducing risk of accidental recursive agent dispatch.
• Returning INVALID-DISPATCH outside an active run preserves the workspace for debugging instead of making unrequested changes.

Practical scenarios

Handing off a multi-step research run

Your subagent gathered sources, wrote notes, and generated a report. Instead of stopping silently, ap-janitor checks the mission pointer in PROMPTS.txt, confirms the governance files and evidence are present, writes DONE, then clears temporary chunks and intermediate search outputs.

Enabling safe retries in an orchestration loop

A nightly automation invokes the same prompt with different inputs. A stale run leaves temp files behind and no completion marker. With ap-janitor, only runs with valid RUN-MARKER and full evidence reach DONE; the orchestrator can confidently clean and retry.

Diagnosing invalid or interrupted dispatches

If an agent is invoked outside an Autoprompt run, ap-janitor immediately returns INVALID-DISPATCH and stops. This leaves the original files untouched, making it easy to inspect why the dispatch lacked the required marker or mission pointer.

Add it to your agent workflow

Install the skill with:

npx skills add Spielewoy/autoprompt-skill --skill ap-janitor

Then invoke it from an active Autoprompt run with a brief that includes the RUN-MARKER, RUN-NONCE, and MISSION POINTER. For example:

Run ap-janitor to finalize this run.
MISSION POINTER: /work/projects/alice/PROMPTS.txt
Expected evidence: /work/projects/alice/output/report.md

The agent will validate all fields before touching any files.

Compare before adopting

Evaluate how strictly ap-janitor validates the three-file governance state and evidence before cleanup. Compare against plain rm scripts: do they write a completion sentinel? Do they verify a mission hash? Also check maintenance freshness, alternatives with similar agent-skill tags, and whether the Autoprompt hierarchy fits your existing orchestration. The skill is a good fit only if you already follow or can adopt its governance file layout.

Why it is worth tracking

ap-janitor has 988 GitHub stars and is maintained by Spielewoy as part of the autoprompt-skill repository. It addresses a real operational gap: agents need a deterministic end-of-run step that marks completion without cluttering state. Track it when you start building multi-run agent workflows and want a reusable terminal leaf for safe cleanup. You can review its positioning and alternatives at OpenAgentSkill.