multi-agent-mux/.agents/skills/multi-agent-mux-reset/SKILL.md

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

name	description	version	author	license	platforms	environments	metadata
multi-agent-mux-reset	Purge the control root's running resident agents and recreate each with the same name, agent, role, herdr server and workspace label, one at a time, with onboarding. Persists .mam/reset-spec.json before the first purge so an interrupted or skipped run resumes where it left off.	4.12.0	godopu	MIT	linux macos	terminal herdr	hermes tags related_skills reset purge recreate lifecycle onboarding multi-agent-mux-stop multi-agent-mux-create multi-agent-mux-status

Multi-Agent Reset

bash .agents/skills/multi-agent-mux-reset/scripts/reset.sh --yes [--dry-run]

Item	Behaviour
Targets	Every registry row with status: running and realpath(pane.cwd) == realpath(WS). Worktree rows, stopped/terminated rows, and orchestrator_uuids are skipped and listed with their reason.
Confirmation	[y/N] prompt; without a terminal -y/--yes is required (exits 3 otherwise). --dry-run inspects without --yes and changes nothing.
Prechecks	Refuses before any change when an open job exists (prints the registry.py ... close --request cancelled command), when .mam/loop-guard-active or .mam/update-in-progress is held, when a target row lacks a valid agent or role, or when the caller itself is one of the targets.
Lock & concurrency	Takes update admission (mam_update_admit), acquires .mam/loop-guard-active (mam_acquire_loop_lock), then releases update admission so run_loop.sh, update.sh, and concurrent resets refuse while the reset runs.
Spec file & rerun	Writes .mam/reset-spec.json atomically before the first stop/purge and removes it only when all targets reach done. Rerunning resumes from the spec file without re-purging already recreated agents (created or done).
Sequence per target	Sequential (never parallel): ① normal stop_session.sh --reason reset (captures verified ID onto the row while herdr is live and sets status: stopped), ② checks that the row has a recorded conversation ID, ③ stop_session.sh --reason reset --purge-conversation --yes (using the row's recorded ID, never a CLI UUID), then create_session.sh with the original name, agent, role, --herdr-session, and --herdr-workspace (onboarding enabled by default).
When skipped (exit 4)	If step ② finds no recorded ID or step ③ exits 4 (in-use gate), the target is skipped and the reset continues to the next agent: the skipped agent is stopped but resumable (its row keeps its id) and its conversation files are untouched; rerun once its holders end, or resume it.

Exit	Meaning
0	All targeted agents reached done and .mam/reset-spec.json was removed; or nothing to reset, cancelled at prompt, or --dry-run with no blockers
1	Refused by precheck (nothing changed), corrupt/mismatched .mam/reset-spec.json, or a stop/create step failed (.mam/reset-spec.json is kept so rerunning resumes)
2	Invalid arguments
3	Not a terminal and -y/--yes was not passed; nothing was changed
4	Completed the pass, but one or more agents were skipped (purge refused with stop exit 4, or no conversation ID recorded); .mam/reset-spec.json is kept for rerun
5	No agent was skipped or failed, but one or more newly created post-discovered agents do not have their new conversation ID recorded yet; .mam/reset-spec.json is kept so rerunning re-checks without re-purging
other	Under set -e, an unexpected sub-step failure passes its nonzero exit code through

Safety Notes

• Irreversible: purged conversations cannot be recovered. Confirm with --dry-run first.
• No external process termination: processes holding conversation files open (reported via lsof in in_use_hints) are never signalled by MAM; end them yourself when safe, then rerun.
• Shared stores preserved: Grok's shared memory-v2.db is left intact during purge; only session rows and per-session files are removed.
• Orchestrator hook during reset: while .mam/loop-guard-active is held by the reset, the AGY orchestrator's direct file-edit hook (loop_delegation_guard.sh) blocks direct edits until the reset finishes.
• Post-precheck job submissions: multi-agent-mux-delegate-job submit does not check .mam/loop-guard-active; do not submit new jobs to resident agents while a reset is running.
• Same-type post-discovered ordering: when resetting multiple post-discovered agents of the same type, the second create_session.sh waits up to MAM_ID_ORDER_WAIT_S for the first agent's ID to be recorded; if it times out, rerun the reset once the ID is recorded.