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.14.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	Without -y/--yes it warns that the conversations are deleted for good and asks [y/N]; without a terminal it cannot ask, so -y/--yes is required (exits 3 otherwise). --dry-run inspects without --yes and changes nothing. An agent has no terminal here: show the user the --dry-run targets, say the deletion cannot be undone, and pass --yes only after they confirm.
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; created when absent, skipped when it cannot be created, since nothing can be registered there), each under that registry's lock, before the check, and on exit removes the directories it created if they are still empty. It refuses, changing nothing, when a registry shared with another workspace is already fenced by that workspace's live reset; it never replaces or removes another reset's marker. 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.