/session-gc - Session Garbage Collection

Garbage collect dead sessions from the session registry, prune stale task claims, clean file locks from dead PIDs, and trigger a quick vacuum sweep for orphaned tasks.

Usage

/session-gc                    # Full GC: prune dead sessions + quick vacuum
/session-gc --dry-run          # Preview what would be cleaned
/session-gc --json             # JSON output
/session-gc --no-vacuum        # Skip the quick vacuum sweep

Options

Option	Description
--dry-run	Preview cleanup actions without executing
--json	Output as JSON instead of formatted text
--no-vacuum	Skip the quick vacuum sweep after GC
--core-dir PATH	Override coditect-core directory path

What Gets Cleaned

Target	Criteria	Action
Dead session entries	session_registry rows where PID is not running	Mark status = ended
Stale task claims	task_claims rows where owner PID is dead	Delete claim row
Stale file locks	file_locks rows where owner PID is dead	Delete lock row
Stale alerts	session_messages with status = 'pending' older than 7 days	Mark as expired

System Prompt

EXECUTION DIRECTIVE: When the user invokes /session-gc, you MUST:

1. Run session cleanup via the message bus:

import os, sys
sys.path.insert(0, 'submodules/core/coditect-core')
from scripts.core.session_message_bus import get_session_message_bus

bus = get_session_message_bus()

# Step 1: Clean dead sessions and stale claims
bus._cleanup_stale_sessions()

# Step 2: Get stats for reporting
stats = bus.stats()

2. Run quick vacuum sweep (unless --no-vacuum):

from scripts.core.context_vacuum import ContextVacuum

vacuum = ContextVacuum()
report = vacuum.quick_sweep()
orphan_summary = vacuum.format_report(report, compact=True)

3. Display results:

Session GC Complete
===================
Dead sessions cleaned: 3
Stale claims pruned: 2
File locks released: 0
Stale alerts expired: 5

Active sessions: 2
Active claims: 3
Active locks: 0

Orphaned Tasks: 1 (1 dead claim)
Run /vacuum for full analysis

CLI alternative:

python3 scripts/core/context_vacuum.py --quick   # Quick sweep includes GC

Example Output

Standard GC

Session GC Complete — 2026-02-12
===================================
Cleaned:
  Dead sessions: 3 (claude-55631, claude-9958, codex-41200)
  Stale claims: 2 (H.13.9.7, N.6.10.5)
  File locks: 0
  Stale alerts: 5

Current state:
  Active sessions: 2
  Active claims: 3
  Active locks: 0

Quick Vacuum: Orphaned Tasks: 0

Dry Run

Session GC Dry Run — 2026-02-12
===================================
Would clean:
  Dead sessions: 3 (claude-55631, claude-9958, codex-41200)
  Stale claims: 2 (H.13.9.7, N.6.10.5)
  File locks: 0
  Stale alerts: 5

No changes made (--dry-run)

Integration Points

System	Integration
/orient	Quick vacuum runs at Step 0c, which surfaces orphans from dead sessions
/session-end	Warns about uncompleted tasks before ending
/vacuum	Full orphan analysis — /session-gc handles just the cleanup subset
_cleanup_stale_sessions()	Existing bus method — /session-gc wraps it with reporting

Related

• Command: /vacuum — Full orphan detection and analysis (ADR-178)
• Command: /session-end — End session with cleanup
• Command: /session-status — View active sessions
• ADR: ADR-178 — Orphan Task Detection
• ADR: ADR-160 — Messaging Architecture
• Script: session_message_bus.py — _cleanup_stale_sessions()
• Script: context_vacuum.py — Quick sweep

Success Output

COMMAND COMPLETE: /session-gc
Dead sessions: 3
Stale claims: 2
Orphans: 0
Duration: 0.8s

---

Command Version: 1.0.0 Created: 2026-02-12 Author: Claude (Opus 4.6) ADR: ADR-178 Track: H.13.10