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

name, description, version, author, license, platforms, environments, metadata

name	description	version	author	license	platforms	environments	metadata
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.	4.4.2	godopu	MIT	linux macos	terminal herdr	hermes tags related_skills prereq_skills agent herdr claude antigravity agy hermes grok opencode codex orchestrator onboard isolation multi-agent-mux-create multi-agent-mux-resume multi-agent-mux-monitor multi-agent-mux-create

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.
• --remove <uuid>: Remove the specified UUID from the orchestrator_uuids list.
• --purge-conversation: With --remove, also delete the conversation's on-disk artifacts through its agent adapter (Issue #13). Irreversible — requires --yes; refused (exit 5, registration untouched) while a live process still references the conversation, e.g. when run from inside that very session.
• --yes: Skip the --purge-conversation confirmation (without it the script prints the danger notice and exits 4).
• --agent <name>: Adapter to purge with (claude|agy|hermes|grok|opencode|codex). Default auto: each adapter is asked whether it owns an artifact for the UUID (agy → ~/.gemini/antigravity-cli/conversations/<uuid>.db etc.). Needed because orchestrator_uuids stores bare UUIDs, not the agent kind.
• --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.

Purging the orchestrator conversation

multi-agent-mux-stop --purge-conversation only reaches sessions that have a herdr_sessions row; the orchestrator never has one. To wipe an orchestrator conversation for good:

.agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --remove <uuid> --purge-conversation --yes
# purged: ~/.gemini/antigravity-cli/conversations/<uuid>.db
# purged: ~/.gemini/antigravity-cli/brain/<uuid>
# ...
# residual: none (agent: agy)

The purge runs before the registry update, so a refused purge (conversation in use, exit 5) changes nothing. If no adapter finds an artifact for the UUID the registration is still removed with a warning. For agy the adapter also removes the SQLite sidecars (-wal/-shm/-journal), the title annotation and the presence lock (Issue #10) and reports anything under ~/.gemini/antigravity-cli that still carries the UUID as WARN residual:.

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, grok, opencode, codex) in the following order:

1. CLI argv:
   • claude -r <uuid> / claude --session-id <uuid>
   • agy --conversation <uuid>
   • grok --session-id <uuid> / grok --resume <uuid>
   • opencode --session <uuid>
   • codex resume <uuid>
2. Family-Matched Environment Variables:
   • claude → CLAUDE_CODE_SESSION_ID
   • agy → ANTIGRAVITY_CONVERSATION_ID
   • hermes → HERMES_SESSION_ID
   • grok → GROK_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 (including --purge-conversation without --remove).
• 3: Detection failed — ID could not be determined.
• 4: --purge-conversation needs --yes — nothing changed.
• 5: Purge refused — the conversation is still in use by a live process; nothing changed.