multi-agent-mux/.agents/skills/multi-agent-mux-orc-onboard/SKILL.md

name, description

name	description
multi-agent-mux-orc-onboard	Register current or specified orchestrator session UUID into agent-sessions.yaml orchestrator_uuids list to prevent sub-agent discovery capture.

multi-agent-mux-orc-onboard

Registers an orchestrator session UUID into the orchestrator_uuids list of .mam/agent-sessions.yaml (and underlying state DB). This ensures that find_workspace_uuid and verify_session_uuid in lib.sh exclude orchestrator conversations when discovering unassigned sub-agent session UUIDs.

Usage

.agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh [OPTIONS]

Options

• --uuid <uuid>: Explicitly register the specified orchestrator session UUID (UUID format or cline ID format).
• --remove <uuid>: Remove the specified UUID from the orchestrator_uuids list.
• --list: Display all currently registered orchestrator UUIDs.
• --no-autodetect: Disable process ancestry auto-detection when --uuid is not provided.
• --dry-run: Output proposed changes without mutating the state registry.

Auto-Detection Hierarchy (Rev.2)

When --uuid is omitted, orc_onboard.sh inspects the process ancestry tree of the nearest agent ancestor (claude, agy, hermes, cline) in the following order:

1. CLI argv:
   • claude -r <uuid> / claude --session-id <uuid>
   • agy --conversation <uuid>
   • cline --id <uuid> / cline --session-id <uuid>
2. Family-Matched Environment Variables:
   • claude → CLAUDE_CODE_SESSION_ID
   • agy → ANTIGRAVITY_CONVERSATION_ID
   • hermes → HERMES_SESSION_ID
   • cline → CLINE_SESSION_ID
3. Fallback:
   • If no valid ID matching the nearest agent family is found, exits with status 3 (Could not detect orchestrator ID).

Exit Statuses

• 0: Success (registered, removed, listed, or already present).
• 1: Conflict — the ID is currently owned by a running sub-agent session row.
• 2: Invalid arguments or malformed ID format.
• 3: Detection failed — ID could not be determined.