feat(skill): implement multi-agent-mux-orc-onboard skill and orchestrator_uuids exclusion gate (40/40 PASS)

2026-08-12 12:49:33 +09:00
parent 1e1ab8ce06
commit 6be1b6aecb
11 changed files with 1430 additions and 5 deletions
@@ -0,0 +1,43 @@
+---
+name: multi-agent-mux-orc-onboard
+description: 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
+
+```bash
+.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.