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.13.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). Rows with any other status, worktree 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, when a running claude/grok target has no recorded conversation id (the monitor had not pinned one; record it, or stop/purge it by hand first), when .mam/reset-spec.json is invalid, or when the caller itself is one of the targets.
Lock & concurrency	Takes the update admission lock exclusively, acquires .mam/loop-guard-active and publishes .mam/reset-in-progress, then releases the admission lock and runs the prechecks. run_loop.sh, update.sh and another reset refuse on the loop marker. The reset then writes .reset-in-progress into every job registry its open-job check reads (.mam/jobs, MAM_JOBS_DIR, and a row's other control_plane.mam_jobs_dir), each under that registry's lock, before the check. A registration (multi-agent-mux-delegate-job submit, registry.py register, the registry API) into a fenced registry - by any path to that directory - refuses; in another control plane's registry only for this workspace's sessions. The onboarding jobs of the reset's own create_session.sh are let through.
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): ⓪ re-checks that its row still has the spec's agent and herdr server and that no job addressed to it is open, ① normal stop_session.sh --reason reset (a post-discovered agent's id is captured onto the row while herdr is live; status: stopped), ② checks that the row's id is the one recorded before the stop and, for a post-discovered agent, that it still verifies as a conversation of the row's folder, ③ 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)	The target is skipped and the reset continues to the next agent when step ⓪ finds a changed row (row changed) or an open job (job open) - nothing was changed for it -, or when step ② finds no id (no conversation id recorded) or an id other than the recorded one or one that does not verify for the row's folder (id not verified), or step ③ exits 4 (purge refused, in-use gate) - it is stopped but resumable (its row keeps its id) and its conversation files are untouched. Rerun once the cause is gone, 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 (see When skipped); .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	130 / 143 / 129 when interrupted by SIGINT / SIGTERM / SIGHUP (the in-flight stop/create ends first, nothing further runs, .mam/reset-spec.json is kept); otherwise, under set -e, an unexpected internal 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.
• Job submissions during a reset: multi-agent-mux-delegate-job submit and registry.py register refuse with a reset of <WS> is in progress until the reset ends (a marker left by a killed reset is stale and ignored); submit again afterwards. A record written into .mam/jobs by hand for a target after the precheck makes that target job open (skipped, not cancelled) if it is there before that target's stop.
• 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.