Skip to content

Conversation

@christauff
Copy link

@christauff christauff commented Jan 31, 2026

Summary

When parallel agents crash (e.g., during RedTeam analysis with 32 agents), orphaned tasks accumulate in TaskList. No automatic cleanup exists, requiring human intervention.

This PR adds an external TaskRegistry that tracks task→PID mappings, with a SessionStart hook that uses kill -0 to detect dead processes and identify orphans factually.

Key insight from RedTeam analysis: Documentation-based cleanup ("please clean up stale tasks") has zero enforcement power. Process liveness checks provide FACTS, not suggestions.

Changes

  • TaskRegistry.ts - External task tracking with PID, session ID, timestamps
  • TaskHygiene.hook.ts - SessionStart hook detecting orphans via kill -0
  • TaskRegistration.hook.ts - PreToolUse hook registering tasks with current PID
  • Updated INSTALL.md with new hook documentation

How It Works

  1. When TaskCreate is called, TaskRegistration.hook.ts records the task ID + current PID in an external registry
  2. When TaskUpdate marks a task completed/deleted, it's removed from the registry
  3. At SessionStart, TaskHygiene.hook.ts checks each registered task's PID:
    • If kill -0 $pid fails, the process is dead → orphaned task
    • Output specific task IDs with verified dead PIDs for cleanup
  4. Claude receives facts ("PID 88888 is dead"), not suggestions ("please clean up stale tasks")

Test plan

  • Create parallel agents that create tasks
  • Kill an agent mid-execution (Ctrl+C)
  • Restart session
  • Verify TaskHygiene hook detects orphans with dead PIDs
  • Verify cleanup instructions are emitted

🤖 Generated with Claude Code

…ement

Problem: When parallel agents crash (e.g., during RedTeam analysis with 32 agents),
orphaned tasks accumulate in TaskList. No automatic cleanup exists, requiring
human intervention.

Solution: External TaskRegistry that tracks task→PID mappings, with SessionStart
hook that uses `kill -0` to detect dead processes and identify orphans factually.

Key insight from RedTeam analysis: Documentation-based cleanup ("please clean up
stale tasks") has zero enforcement power. Process liveness checks provide FACTS,
not suggestions.

New files:
- TaskRegistry.ts: External task tracking with PID, session ID, timestamps
- TaskHygiene.hook.ts: SessionStart hook detecting orphans via kill -0
- TaskRegistration.hook.ts: PreToolUse hook registering tasks with PID

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant