Shared Lifecycle

Shared Lifecycle

"Cleanup after yourself. Don't leave processes running when you exit."

Process Management Golden Rules

1. Check the process registry before starting a process
2. Register processes you start
3. Cleanup your processes when done
4. Never start a duplicate process if one is running
5. Never leave background processes running when you exit

Process Registry

Location: ./.claude/session/process-registry.json

The registry tracks all running processes across all agents.

Format:

{
  "version": "1.0",
  "lastUpdated": "2026-01-26T10:00:00Z",
  "processes": {
    "dev-server-3000": {
      "name": "dev-server",
      "port": 3000,
      "pid": 12345,
      "agent": "qa",
      "startedAt": "2026-01-26T09:55:00Z",
      "command": "npm run dev",
      "status": "running",
      "purpose": "browser-validation"
    }
  },
  "agents": {
    "qa": ["dev-server-3000"],
    "developer": [],
    "pm": []
  }
}

Using Read/Write Tools

Check registry:

Read: ./.claude/session/process-registry.json

Update registry:

Edit: ./.claude/session/process-registry.json

Background Process Management

Starting Background Processes

Using Bash tool with run_in_background=true:

# Start dev server in background
Bash(command="npm run dev", run_in_background=true)
# Returns: { shell_id: "abc123" }

Capture the shell_id — you need it for cleanup!

Checking Port Availability

Before starting a process that binds to a port:

# Check if port is in use
Bash(command="netstat -an | grep :3000 || echo 'Port 3000 available'")

Cleanup is MANDATORY

Before updating status to "idle" or reporting task complete:

# Kill the background process using shell_id
TaskStop(task_id="abc123")

Cleanup Checklist

CRITICAL: Always stop background processes before exit

• Kill ALL background processes (use TaskStop with shell_id)
• Process registry updated (processes removed from agent's list)
• Ports are released (verify with netstat/lsof)
• No orphaned node/npm processes remain

Message Transaction Lifecycle

Your work is transactional. The Watchdog considers you "busy" until you explicitly say otherwise.

1. Source of Truth

• Inbox: ./.claude/session/messages/{agent}/
• Transaction File: ./.claude/session/pending-messages-{agent}.json

Messages move from Inbox -> Transaction File. Once delivered, transaction file is the active batch lock.

2. Do Not Delete Messages

• Never delete message files from ./.claude/session/messages/.
• Never delete pending-messages-{agent}.json.
• The Watchdog exclusively handles queue and pending cleanup.

3. Closing the Transaction

You must explicitly signal when you are done with the current batch of messages.

Send a status_update message:

• Type: status_update
• To: watchdog
• Status: idle, waiting, or ready

Effect: This marks the batch as complete/available so Watchdog can safely unlock and deliver next queued batch.

Cleanup Pattern (Even on Failure)

Always cleanup in a finally pattern:

1. Start background process (capture shell_id)
2. Try:
   - Do the work
3. Finally:
   - Stop background process (TaskStop with shell_id)
   - Update process registry
4. Only THEN: Update task status

Anti-pattern: ❌ Exiting without stopping background processes Good pattern: ✅ Always cleanup, even if work fails

Auxiliary Scripts

Scripts in ./.claude/session/ help with automation and cleanup.

Script Classification

Creating Reusable Scripts

If you create a helper script that provides value:

1. Document purpose — Add comment header
2. Use descriptive naming — {agent}-{purpose}.sh
3. Track usage — Note which agents use it
4. Explain value — Future sessions should understand why it exists

Script Permissions

• Scripts in ./.claude/session/ executable by all agents
• Never create scripts that modify source code without explicit task
• Scripts should only update session files or state files

Anti-Patterns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.