/vacuum - Context Vacuum Orphan Detection
Detect orphaned tasks — work that was started, claimed, or partially completed but abandoned when sessions died, contexts compacted, or projects were parked.
Usage
/vacuum # Standard sweep (10-30s)
/vacuum --quick # Quick sweep (<2s, messaging.db only)
/vacuum --deep # Deep sweep (2-5 min, full history + git)
/vacuum --adopt <task_id> # Claim an orphaned task for this session
/vacuum --defer <task_id> # Mark orphan as intentionally deferred
/vacuum --cancel <task_id> # Mark orphan as no longer needed (confirmation required)
/vacuum --json # JSON output
/vacuum --compact # One-line summary (for /orient integration)
Options
| Option | Description |
|---|---|
--quick | Quick sweep — dead PIDs, stale claims, unresolved alerts. <2s. |
--deep | Deep sweep — adds full session log history, git commit correlation, lifecycle timelines |
--adopt TASK_ID | Claim an orphaned task, broadcast adoption to message bus |
--defer TASK_ID | Mark orphan as intentionally deferred |
--cancel TASK_ID | Mark orphan as no longer needed (requires confirmation) |
--json | Output as JSON instead of formatted text |
--compact | One-line summary: "Orphaned Tasks: 3 (2 dead claims, 1 stale)" |
--core-dir PATH | Override coditect-core directory path |
Sweep Modes
Quick Sweep (--quick)
Cost: <2 seconds. Queries only messaging.db.
| Check | Source | Orphan Signal |
|---|---|---|
| Dead PID claims | task_claims + session_registry | Claimed task, owner PID not running |
| Stale claims | task_claims WHERE claimed_at > 24h | Long-running claim, possibly abandoned |
| Unresolved conflicts | session_messages WHERE message_type = 'task_conflict' | Conflict alert never resolved |
Runs automatically on /orient.
Standard Sweep (default)
Cost: 10-30 seconds. Cross-references TRACK files + messaging.db + session logs (30 days).
| Data Source | What it provides |
|---|---|
TRACK files [ ] | All unchecked tasks with IDs |
messaging.db task_claims | Which tasks were claimed, by whom, when |
messaging.db session_messages | Last activity timestamp per task |
| Session logs (30 days) | Task ID mentions with timestamps |
Orphan classification:
| Type | Criteria |
|---|---|
dead_claim | task_claims row exists, PID not running |
stale_in_progress | Last activity >7 days ago, still [ ] |
conflict_abandoned | task_conflict alert unresolved |
parked_project | Track at 0% or >30 days inactive, no active claims |
Deep Sweep (--deep)
Cost: 2-5 minutes. Full historical analysis.
Adds to Standard Sweep:
- All session logs (365 days, not just 30)
- Git commit correlation (
feat(H.13.9):pattern matching) - Task lifecycle timeline per task ID
- Cross-reference with git history
System Prompt
EXECUTION DIRECTIVE:
When the user invokes /vacuum, you MUST:
- Import and instantiate the Context Vacuum:
import sys
sys.path.insert(0, 'submodules/core/coditect-core')
from scripts.core.context_vacuum import ContextVacuum
vacuum = ContextVacuum()
- Run the appropriate sweep:
# Default: standard sweep
report = vacuum.standard_sweep()
# Quick sweep
report = vacuum.quick_sweep()
# Deep sweep
report = vacuum.deep_sweep()
- Display the report:
print(vacuum.format_report(report))
# Or compact: print(vacuum.format_report(report, compact=True))
# Or JSON: import json; print(json.dumps({...}))
- For actions (adopt/defer/cancel):
vacuum.adopt_task("H.13.9.7") # Claims task, broadcasts to bus
vacuum.defer_task("K.3.1") # Marks as deferred
vacuum.cancel_task("K.3.1") # Marks as cancelled (ask confirmation first)
CLI alternative:
python3 scripts/core/context_vacuum.py # Standard sweep
python3 scripts/core/context_vacuum.py --quick # Quick sweep
python3 scripts/core/context_vacuum.py --deep # Deep sweep
python3 scripts/core/context_vacuum.py --adopt H.13.9.7 # Adopt orphan
python3 scripts/core/context_vacuum.py --json # JSON output
Example Output
Standard Sweep
Context Vacuum Report - 2026-02-12
=======================================================
Sweep: standard | Duration: 12453ms
ORPHANED TASKS (action required):
[DEAD_CLAIM ] H.13.9.7 Documentation updates Last: 2026-02-11T15:30:00Z (claude-55631)
[STALE 14d ] J.29.3.2 Dashboard data refresh Last: 2026-01-29T10:00:00Z
[CONFLICT ] N.6.10.5 Test validation Last: 2026-02-10T18:00:00Z (claude-9958)
PARKED PROJECTS (no activity >30 days):
Track K 75 tasks, 0% done, last activity: never
Track G 64 tasks, 0% done, last activity: never
RECENTLY ACTIVE: 5 tasks (no action needed)
Summary: 3 orphans, 2 parked tracks, 1216 total unchecked
Run /vacuum --adopt <task_id> to claim an orphan
Quick Sweep (compact, for /orient)
Orphaned Tasks: 2 (1 dead claim, 1 conflict)
Integration Points
| System | Integration |
|---|---|
/orient | Quick sweep runs automatically (Step 0). Shows orphan count. |
/next-task | vacuum.get_orphan_priority_list() — prioritizes orphans over fresh work |
/session-end | vacuum.check_uncompleted_tasks() — warns if session has uncompleted claims |
/session-gc | Clean dead claims, trigger quick sweep |
Storage
Vacuum results stored in messaging.db → vacuum_reports table:
CREATE TABLE IF NOT EXISTS vacuum_reports (
id INTEGER PRIMARY KEY AUTOINCREMENT,
sweep_type TEXT NOT NULL,
created_at TEXT NOT NULL,
task_id TEXT NOT NULL,
orphan_type TEXT NOT NULL,
last_activity TEXT,
last_session_id TEXT,
track TEXT,
description TEXT,
evidence TEXT, -- JSON
resolution TEXT, -- NULL, adopted, completed, deferred, cancelled
resolved_at TEXT,
resolved_by TEXT
);
Related
- ADR: ADR-178 — Orphan Task Detection and Context Vacuum
- Script: context_vacuum.py — Implementation
- Track: H.13.10 in TRACK-H-CEF-EXPERIENCE-FRAMEWORK.md
- Depends on: session_message_bus.py — messaging.db access
Success Output
COMMAND COMPLETE: /vacuum
Sweep: standard
Orphans: 3 (1 dead_claim, 1 stale, 1 conflict)
Parked tracks: 2
Duration: 12.4s
Results stored in messaging.db
Command Version: 1.0.0 Created: 2026-02-12 Author: Claude (Opus 4.6) ADR: ADR-178 Track: H.13.10