GodopuandClaude Opus 5
4176d7570f
PATCH release for the fix/issue-12-8-7 branch (Issue #12 broker password
kept out of job records, #8 fresh install stamps kept on update, #7
same-cwd workspaces packed). No code logic changes.
- lib.sh MAM_VERSION, lib_py/loop/eager.py FRAMEWORK_VERSION and the eight
SKILL.md frontmatters (create, stop, resume, status, monitor, delegate-job,
loop, orc-onboard) move from 4.4.3 to 4.4.4
- VERSIONS.md: current release v4.4.4 (2026-09-13 KST), the eight-row skill
matrix, and a v4.4.4 changelog section in the v4.4.3 format covering the
password-free registry block restored from MQTT_PASSWORD at connect time,
the scrub on every record write, `registry.py scrub-secrets [--dry-run]`,
why auth_token/dispatch_token stay, the update.sh stamp and install_state
merge rules, the sibling-workspace walk in new-session, and the 8 new tests
- VERSIONS.md v4.4.3 ledger correction: its new-test count predated fae70c1,
which added two purge tests; now 26 (19 + 7) with both listed
- README, README.ko, BOOTSTRAP and BOOTSTRAP.ko badges and the MESSAGING.md
"Applies to" header follow the current version; historical 4.4.3 mentions
(v4.4.3 changelog, reviewer reports) stay as history
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGpJXhSZasJLU38ksDghe
75 lines
5.1 KiB
Markdown
75 lines
5.1 KiB
Markdown
---
|
|
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."
|
|
version: 4.4.4
|
|
author: godopu
|
|
license: MIT
|
|
platforms: [linux, macos]
|
|
environments: [terminal, herdr]
|
|
metadata:
|
|
hermes:
|
|
tags: [agent, herdr, claude, antigravity, agy, hermes, grok, opencode, codex, orchestrator, onboard, isolation]
|
|
related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-monitor]
|
|
prereq_skills: [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
|
|
|
|
```bash
|
|
.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 — including the session the command itself runs in: its session-id variable (`CLAUDE_CODE_SESSION_ID`, `ANTIGRAVITY_CONVERSATION_ID`, `HERMES_SESSION_ID`, `GROK_SESSION_ID`, `OPENCODE_SESSION_ID`) equals the UUID, or the nearest agent CLI ancestor names it on its command line. An orchestrator therefore cannot purge its own conversation from inside that very session. Any live process whose command line contains the UUID counts, not only a resumed session — an editor, a `grep` or a delegation wrapper whose prompt merely mentions it blocks the purge too; if it is refused, find the process with `ps -axww | grep <uuid>`.
|
|
- `--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:
|
|
|
|
```bash
|
|
.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:`. Orphaned leftovers — a WAL, annotation or lock whose DB is already gone — still resolve to agy and are purged, and the in-use check asks `lsof` about every one of those paths, so a holder that keeps only the presence lock open (naming the UUID nowhere) is refused too.
|
|
|
|
## 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.
|