/session-register

Register the current LLM session with the Inter-Session Message Bus (messaging.db) to enable multi-session coordination, file conflict detection, task claim/release, and automatic conflict detection with operator alerts (ADR-173).

Purpose

Registers the current session in the session_registry table of messaging.db (ADR-160) with PID, LLM vendor/model, project ID, and task context. Automatically broadcasts a session_lifecycle/started event and runs conflict detection (ADR-173) against other active sessions. Other sessions can then detect conflicts, coordinate task ownership, and see cross-LLM status.

Usage

# Auto-detect LLM and register
/session-register

# Register with specific LLM and task
/session-register --llm codex --task-id J.15.6

# Register with project override
/session-register --project PILOT

Arguments

Argument	Type	Required	Default	Description
`--llm`	string	No	auto-detect	LLM vendor: claude, codex, gemini, kimi
`--model`	string	No	auto-detect	LLM model: opus-4.6, o3, 2.5-pro, k2
`--task-id`	string	No	""	Current task ID (e.g., H.13.2)
`--project`	string	No	auto-detect	Project ID (auto-detected via discover_project())
`--verbose`	flag	No	false	Show detailed registration output

System Prompt

When the user invokes /session-register:

Auto-detect LLM and project:

import os
from scripts.core.session_message_bus import get_session_message_bus
from scripts.core.paths import discover_project

pid = os.getpid()
project = discover_project() or "unknown"
# LLM vendor detected from process name / env vars

Register with message bus:

bus = get_session_message_bus()
bus.register_session(
    session_id=f"claude-{pid}",
    llm_vendor="claude",
    llm_model="opus-4.6",
    project_id=project,
    pid=pid
)

Optionally set current task:

if task_id:
    bus.update_session_task(task_id, session_id=f"claude-{pid}")

Start heartbeat thread (background, every 30s):

bus.start_heartbeat_thread(interval=30, session_id=f"claude-{pid}")

Check for conflicts and unread messages (ADR-173):

# Registration auto-broadcasts session_lifecycle/started and runs _detect_conflicts()
# Now check what was found:
alerts = bus.get_operator_alerts(unread_only=True, limit=10)
unread = bus.get_unread(recipient_id=f"claude-{pid}", limit=10)

Output result:

Session registered: claude-{pid}
  Vendor:  claude (opus-4.6)
  Project: PILOT
  Task:    H.13.2
  PID:     {pid}
  Bus:     messaging.db

If conflicts detected (ADR-173), also show:

CONFLICTS DETECTED:
  [CRITICAL] project_conflict: codex-41200 also on PILOT
  [HIGH] cwd_overlap: codex-41200 in same directory

Run /session-conflicts --full for details.

If unread messages exist:

UNREAD MESSAGES: 3 (2 operator_alert, 1 task_broadcast)
Run /session-status --unread for details.

Output Examples

Standard Output (No Conflicts)

Session registered: claude-12345
  Vendor:  claude (opus-4.6)
  Project: PILOT
  Task:    H.13.2
  PID:     12345

Lifecycle: session_lifecycle/started broadcast
Conflicts: None detected
Unread: 0 messages

Bus: ~/.coditect-data/context-storage/messaging.db
Run /session-status to see all active sessions.

Output with Conflicts (ADR-173)

Session registered: claude-12345
  Vendor:  claude (opus-4.6)
  Project: PILOT
  Task:    H.13.2
  PID:     12345

Lifecycle: session_lifecycle/started broadcast

CONFLICTS DETECTED:
  [CRITICAL] project_conflict: codex-41200 also on PILOT
  [HIGH] cwd_overlap: codex-41200 in /Users/halcasteel/PROJECTS/coditect-rollout-master

Run /session-conflicts --full for details.

Unread: 2 operator alerts
Run /session-status --alerts for details.

Bus: ~/.coditect-data/context-storage/messaging.db

Verbose Output

Registering session with Inter-Session Message Bus...
  Auto-detected LLM: claude (opus-4.6)
  Resolved project: PILOT (via discover_project())
  Process ID: 12345
  Database: ~/.coditect-data/context-storage/messaging.db

Inserting into session_registry...
Broadcasting session_lifecycle/started event...
Running conflict detection against 1 active session(s)...
  project_conflict detected: codex-41200 (PILOT)
  cwd_overlap detected: codex-41200
Starting heartbeat thread (interval=30s)...

Session registered: claude-12345
  Vendor:  claude (opus-4.6)
  Project: PILOT
  Task:    H.13.2
  PID:     12345
  Bus:     messaging.db (WAL mode, 52 KB)
  Alerts:  2 (project_conflict, cwd_overlap)

What Gets Registered

The session entry is stored in the session_registry table:

INSERT INTO session_registry (session_id, llm_vendor, llm_model, project_id, pid, status)
VALUES ('claude-12345', 'claude', 'opus-4.6', 'PILOT', 12345, 'active');

Fields:

session_id: Unique identifier ({vendor}-{pid})
llm_vendor: claude, codex, gemini, kimi
llm_model: opus-4.6, o3, 2.5-pro, k2
project_id: Auto-detected from discover_project()
pid: OS process ID
task_id: Current task being worked on
heartbeat_at: Updated every 30s by background thread
status: active (set on register), removed on unregister

When to Use

Use this command when:

Starting a new LLM session
Working in a project with other active LLM sessions
Need file lock coordination across sessions
Building multi-LLM workflows (Claude + Codex + Kimi)

Common Workflows

Workflow 1: Session Start

# 1. Start LLM session
claude

# 2. Register immediately
/session-register --task-id H.13

# 3. Check active sessions
/session-status

# 4. Claim a task for exclusive ownership
# (via Python API: bus.claim_task("H.13.7"))

Workflow 2: Multi-LLM Coordination

# Terminal 1: Claude on Track H
/session-register --llm claude --task-id H.13.2

# Terminal 2: Codex on Track J
/session-register --llm codex --task-id J.15.6

# Terminal 3: Check cross-LLM status
/session-status

Integration

Once registered, the session participates in:

Feature	Description
File locks	`bus.lock_file("path")` / `bus.unlock_file("path")`
Task claims	`bus.claim_task("H.13")` - exclusive ownership
Heartbeats	Background thread keeps session alive
Stale cleanup	Sessions with expired heartbeats auto-cleaned
Cross-LLM status	`bus.get_cross_llm_status()` shows all vendors
Project lock-out	`discover_project()` skips projects with active sessions
Lifecycle events (ADR-173)	Auto-broadcast started/ended events
Conflict detection (ADR-173)	Auto-detect project/task/CWD overlaps
Operator alerts (ADR-173)	Receive critical alerts from conflict detection
Directed messaging (ADR-173)	`bus.send()` / `bus.get_unread()`

Error Handling

Error	Cause	Solution
"Database locked"	SQLite contention	Auto-retries with busy_timeout=3000ms
"Permission denied"	Can't write messaging.db	Check ~/.coditect-data permissions
"Session already exists"	Re-registration	Updates existing entry (idempotent)

Success Criteria

Command succeeds when:

Session row inserted in session_registry
Session ID format: {vendor}-{pid}
Heartbeat thread running
Project auto-detected
Success message displayed

Command	Purpose
`/session-status`	Show all active sessions and cross-LLM status
`/session-conflicts`	Check for file lock conflicts
`/session-rescue`	Recover hung/stuck sessions

Architecture

Database: ~/.coditect-data/context-storage/messaging.db (SQLite WAL mode)
Tables: session_registry, session_messages, inter_session_messages, file_locks, task_claims
Python API: scripts/core/session_message_bus.py
ADR: ADR-160, ADR-173
Guide: Multi-Session Coordination Guide

Version: 3.0.0 Created: 2026-02-07 Updated: 2026-02-11 Author: Claude Opus 4.6 Track: H (Framework Autonomy) Task: H.13.9

Changelog:

v3.0.0 - ADR-173 v2: Auto-broadcast session_lifecycle/started, auto-detect conflicts (project/task/CWD), show operator alerts and unread messages on registration
v2.0.0 - Inter-Session Message Bus integration (ADR-160)
v1.0.0 - Basic session registration

Purpose​

Usage​

Arguments​

System Prompt​

Output Examples​

Standard Output (No Conflicts)​

Output with Conflicts (ADR-173)​

Verbose Output​

What Gets Registered​

When to Use​

Common Workflows​

Workflow 1: Session Start​

Workflow 2: Multi-LLM Coordination​

Integration​

Error Handling​

Success Criteria​

Related Commands​

Architecture​