docs(issue-42): stages 1-2 - SKILL.md code-block inventory as test data; remove blocks the scripts already do
Stage 1: tests/data/skill_code_blocks.json lists all 37 fenced blocks of the
eight SKILL.md files at base 45d1621 (indented fences count), classed (a)
duplicate of a script, (b) procedure no script offers, (c) example/call/
diagram, with script file:line evidence and recorded mismatches.
tests/test_issue42_skill_blocks.py fails when a block changes without the
inventory, an (a) block comes back, a removed block's entry call is missing,
an exit-code table drifts from the script, or evidence points nowhere.
Stage 2: the five (a) blocks are gone - resume Workflow, stop pre-flight,
create pre-flight / Workflow / manual YAML append - replaced by the
entry-point call with option and exit-code tables. Each exit table has a
catch-all row: under set -e a failing sub-step's code passes through.
create's exit 4 is real (the YAML write raises SystemExit(4) for a duplicate
running row) and is listed as such. Doc-to-script mismatches are fixed in the
doc (resume Case 3 / no attach, stop --purge-conversation --yes, status
--json keys, create cmd_full and the nonexistent yaml-edit script). No
behaviour change, no version bump.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
GodopuandClaude Opus 5.5 committed
1 parent
45d1621c93
commit
7670b41afd
6 files changed
+901
-226
No files matched your search
@@ -30,28 +30,9 @@ So `$WORKSPACE_ROOT/landing_page/refer_landing_page` + `claude` → `landing-pag
|
||||
|
||||
## Pre-flight checks
|
||||
|
||||
Before doing anything, verify the environment:
|
||||
`create_session.sh` checks the environment itself and exits 1 if anything is missing: herdr installed (`has_real_herdr`), the agent CLI in `PATH`, the agent's authentication, and the workspace directory. In your own scripts, test for herdr with lib.sh's `has_real_herdr`, NOT `command -v herdr` / `type -P herdr`: once lib.sh is sourced the former matches its `herdr()` function and the latter matches the `.mam/shim` wrapper, so both pass on a host with no herdr (B-3).
|
||||
|
||||
```bash
|
||||
# 1) herdr available and isolated server status
|
||||
# Use lib.sh's has_real_herdr, NOT `command -v herdr` / `type -P herdr`: once
|
||||
# lib.sh is sourced the former matches its herdr() function and the latter
|
||||
# matches the .mam/shim wrapper, so both pass on a host with no herdr (B-3).
|
||||
has_real_herdr || { echo "ERROR: herdr not installed"; exit 1; }
|
||||
echo "Herdr session name: ${HERDR_SESSION_NAME:-default}"
|
||||
|
||||
# 2) claude / agy available
|
||||
command -v claude # required for --agent claude
|
||||
command -v agy # required for --agent agy
|
||||
|
||||
# 3) claude auth (if --agent claude)
|
||||
claude auth status 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); assert d.get('loggedIn'), 'claude not logged in'"
|
||||
|
||||
# 4) target workspace exists
|
||||
test -d "$WORKSPACE" || { echo "ERROR: workspace $WORKSPACE not a directory"; exit 1; }
|
||||
```
|
||||
|
||||
If any check fails → abort with a non-zero exit and report the reason (automated path) or report to user (interactive path). Do not proceed with a half-broken setup.
|
||||
If a check fails, report the reason (automated path) or tell the user (interactive path). Do not proceed with a half-broken setup.
|
||||
|
||||
## Standard names
|
||||
|
||||
@@ -163,109 +144,45 @@ herdr_sessions:
|
||||
kill_command: "HERDR_SESSION_NAME=<herdr_session> herdr kill-session -t <SESSION_NAME>"
|
||||
```
|
||||
|
||||
The three commands require `source .agents/skills/lib.sh` first — `new-session`/`kill-session` are tmux-compat pseudo-commands the shim translates, and `HERDR_SESSION_NAME` is what the shim reads to route to the right isolated herdr *session* (real `herdr` has no env-var-based scoping of its own; `herdr_session: default` needs no prefix at all).
|
||||
|
||||
## Workflow
|
||||
|
||||
```bash
|
||||
WORKSPACE=/path/to/project
|
||||
AGENT=claude # claude | agy | hermes | grok | opencode | codex — always pass it explicitly
|
||||
source .agents/skills/lib.sh
|
||||
SESSION_NAME="$(derive_session_name "$WORKSPACE" "$AGENT")"
|
||||
|
||||
# 1. If session already alive, fail fast
|
||||
herdr has-session -t "$SESSION_NAME" 2>/dev/null && {
|
||||
echo "ERROR: herdr session '$SESSION_NAME' already exists. Use multi-agent-mux-resume to attach or multi-agent-mux-stop first."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# 2. Spawn the herdr session with the agent inside
|
||||
case "$AGENT" in
|
||||
claude)
|
||||
# Use the wrapper if it exists, else inline herdr new-session
|
||||
# Use the wrapper if it exists (LOCAL_BIN env var overrides default $HOME/.local/bin)
|
||||
local_bin="${LOCAL_BIN:-$HOME/.local/bin}"
|
||||
if [ -x "$local_bin/$SESSION_NAME" ]; then
|
||||
nohup "$local_bin/$SESSION_NAME" >/dev/null 2>&1 &
|
||||
else
|
||||
herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "claude"
|
||||
fi
|
||||
;;
|
||||
agy)
|
||||
herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "agy --dangerously-skip-permissions"
|
||||
;;
|
||||
hermes)
|
||||
herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "hermes --yolo --accept-hooks"
|
||||
;;
|
||||
grok)
|
||||
herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "grok --permission-mode bypassPermissions"
|
||||
;;
|
||||
opencode)
|
||||
herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "opencode --auto --agent build"
|
||||
;;
|
||||
codex)
|
||||
herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "codex --dangerously-bypass-approvals-and-sandbox"
|
||||
;;
|
||||
*) echo "ERROR: --agent must be claude, agy, hermes, grok, opencode, or codex, got: $AGENT"; exit 2 ;;
|
||||
esac
|
||||
|
||||
# 3. Wait for agent TUI to be ready (varies: claude ~5s, agy ~3s)
|
||||
sleep 6
|
||||
|
||||
# 4. Capture pane metadata
|
||||
PANE_PID=$(herdr list-panes -t "$SESSION_NAME" -F '#{pane_pid}')
|
||||
PANE_CWD=$(herdr list-panes -t "$SESSION_NAME" -F '#{pane_current_path}')
|
||||
PANE_CMD=$(herdr list-panes -t "$SESSION_NAME" -F '#{pane_current_command}')
|
||||
# `herdr list-sessions` doesn't exist (real or shimmed) — we just spawned this
|
||||
# session ourselves, so stamp the epoch locally instead of round-tripping herdr.
|
||||
HERDR_EPOCH=$(date +%s)
|
||||
bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace <path> --agent <agent> --role <role>
|
||||
```
|
||||
|
||||
`create_session.sh` does the whole flow: pre-flight, the session name (`derive_session_name`), the agent command (adapter `spawn-spec`), spawn, start-up dialogs, waiting for the TUI, pane capture, the YAML row, and the optional job submission.
|
||||
|
||||
| Option | Meaning |
|
||||
|---|---|
|
||||
| `--workspace` | Required. Project directory |
|
||||
| `--agent` | Required. `claude`, `agy`, `hermes`, `grok`, `opencode`, `codex` |
|
||||
| `--role` | Required. Assigned role |
|
||||
| `--session` (`--name`) | herdr session name (default: `derive_session_name`) |
|
||||
| `--wrapper` | claude only: use the `~/.local/bin/<session>` wrapper even if it is not present |
|
||||
| `--dry-run` | Print what would be spawned; spawn and write nothing |
|
||||
| `--herdr-session` (`--herdr-server`) | Isolated herdr server name |
|
||||
| `--herdr-workspace` | herdr workspace label recorded in the registry (a label only, never a socket) |
|
||||
| `--submit-job PROMPT` | Register a delegated job with this prompt and send it to the new agent |
|
||||
| `--onboard` / `--no-onboard` | Submit the onboarding job (default: on) |
|
||||
| `--auto-trust` / `--no-auto-trust` | Answer a start-up directory-trust dialog or leave it to a human (`MAM_AUTO_TRUST`; default: answer) |
|
||||
| `--isolate` / `--no-isolate` | Legacy, no-op |
|
||||
|
||||
| Exit | Meaning |
|
||||
|---|---|
|
||||
| 0 | Created; or `--dry-run` |
|
||||
| 1 | Pre-flight failure, nothing was spawned: workspace not a directory, herdr not installed, agent CLI not in `PATH`, agent not authenticated. After spawn: the task brief could not be written or the instruction injection failed (the session is rolled back) |
|
||||
| 2 | Bad arguments; control-plane binding refused for a worktree; whitespace in a control-plane path that must be forwarded |
|
||||
| 3 | A herdr session of that name already exists (`multi-agent-mux-resume`, or `multi-agent-mux-stop` first) |
|
||||
| 4 | The YAML already has a `running` row of that name. The YAML write raises it after spawn, and the herdr session is rolled back |
|
||||
| 42 | The TUI never became ready and the process is gone |
|
||||
| 43 | The rollback could not kill the herdr session; it is still running |
|
||||
| other | A later step failed and its code is passed through. The EXIT trap (`cleanup_herdr_on_error`) rolls back the herdr session and closes the onboarding job as `cancelled`; if that kill fails, the exit is 43 instead |
|
||||
|
||||
## Registering the session in agent-sessions.yaml
|
||||
|
||||
After spawn, append a new `herdr_sessions[]` entry to `.mam/agent-sessions.yaml`:
|
||||
|
||||
```yaml
|
||||
- name: <SESSION_NAME>
|
||||
status: running
|
||||
herdr_session_created_at: 2026-06-17T...Z # ISO 8601 UTC
|
||||
herdr_session_epoch: <HERDR_EPOCH>
|
||||
herdr_session: <HERDR_SESSION_NAME> # Isolated session name (default: 'mam-<ws-slug>')
|
||||
herdr_server: <HERDR_SESSION_NAME> # Alias for herdr_session
|
||||
pane:
|
||||
index: 0
|
||||
pid: <PANE_PID>
|
||||
cmd: <AGENT> # 'claude' or 'agy'
|
||||
cmd_full: <full command line, see table below>
|
||||
cwd: <PANE_CWD>
|
||||
tui: # only for claude
|
||||
model: <from TUI status>
|
||||
provider: <from TUI status>
|
||||
plan: <from TUI status>
|
||||
account: <from TUI status>
|
||||
version: <from TUI status>
|
||||
start_command: "HERDR_SESSION_NAME=<herdr_session> herdr new-session -d -s <SESSION_NAME> -x 140 -y 40 -c <WORKSPACE> <CMD_FULL>"
|
||||
attach_command: "HERDR_SESSION_NAME=<herdr_session> herdr agent attach <SESSION_NAME>"
|
||||
kill_command: "HERDR_SESSION_NAME=<herdr_session> herdr kill-session -t <SESSION_NAME>"
|
||||
# All three require `source .agents/skills/lib.sh` first — `new-session`/`kill-session`
|
||||
# are tmux-compat pseudo-commands the shim translates, and `HERDR_SESSION_NAME` is what
|
||||
# the shim reads to route to the right isolated herdr *session* (real `herdr` has no
|
||||
# env-var-based scoping of its own; `herdr_session: default` needs no prefix at all).
|
||||
```
|
||||
|
||||
`cmd_full` per agent (this is the actual command line in the pane, not the resume command):
|
||||
|
||||
| agent | cmd_full |
|
||||
|---|---|
|
||||
| claude (interactive) | `claude` |
|
||||
| agy (interactive) | `agy --dangerously-skip-permissions` |
|
||||
|
||||
Use the `agent-sessions-yaml-edit` script in `scripts/` to safely append (preserves comments + format):
|
||||
|
||||
```bash
|
||||
bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
|
||||
--workspace "$WORKSPACE" --agent "$AGENT" --role "$ROLE" --session "$SESSION_NAME"
|
||||
```
|
||||
|
||||
The script handles the YAML append, pane capture, and the `last_visible_status` placeholder.
|
||||
`create_session.sh` writes the `herdr_sessions[]` row itself (the format is in **Output format** above); do not append it by hand. `pane.cmd_full` is the actual command line in the pane, decided by the adapter `spawn-spec` (`lib_py/agents`), not the resume command.
|
||||
|
||||
## Issue worktrees: `worktree_prepare.sh` (Issue #21 item 4)
|
||||
|
||||
@@ -321,7 +238,7 @@ print('OK:', names)
|
||||
herdr agent read "$SESSION_NAME" --source visible --lines 20 # TUI ready = agent banner visible, no dialog text
|
||||
```
|
||||
|
||||
> `herdr has-session` / `herdr list-panes` / `herdr capture-pane` above are tmux-compat pseudo-commands only understood after `source .agents/skills/lib.sh` (see `Workflow`) — the real `herdr` binary has no such subcommands. The block above uses the real `herdr agent get`/`herdr agent read` equivalents so it also works standalone.
|
||||
> `herdr has-session` / `herdr list-panes` / `herdr capture-pane` are tmux-compat pseudo-commands only understood after `source .agents/skills/lib.sh` — the real `herdr` binary has no such subcommands. The block above uses only the real `herdr agent get`/`herdr agent read` commands, so it works standalone.
|
||||
|
||||
## When NOT to use this skill
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ Three cases this skill handles:
|
||||
|
||||
1. **herdr is dead, conversation lives** — `agent-sessions.yaml` has the UUID. The JSONL/db is on disk. Re-spawn the herdr session + run `claude -r <id>` / `agy --conversation <id>`.
|
||||
2. **herdr is alive but empty** — You started a session with `multi-agent-mux-create` but haven't sent a message yet (so no session id was assigned). The user can either send their first message (and the id is auto-assigned), or you can read the *workspace's* most recent conversation from `$HOME_DIR/.gemini/antigravity-cli/cache/last_conversations.json` (defaults to `~/.gemini/...`) for agy, or the latest `*.jsonl` in `$CLAUDE_PROJECT_DIR/<workspace-key>/` (defaults to `~/.claude/projects/`) for claude.
|
||||
3. **herdr is alive AND the agent inside is already running** — Just attach. No re-spawn needed.
|
||||
3. **herdr is alive AND the agent inside is already running** — `resume_session.sh` only updates the row and exits 0. It does not attach and does not check the agent's permission flags (#45); attach with `herdr agent attach <name>`.
|
||||
|
||||
### Resuming a `stopped` session (`stopped → running`)
|
||||
|
||||
@@ -57,66 +57,30 @@ If both are empty → for Class A agents (`agy`, `hermes`, `opencode`, `codex`),
|
||||
## Workflow
|
||||
|
||||
```bash
|
||||
WORKSPACE=/path/to/project
|
||||
AGENT=claude # claude | agy | hermes | grok | opencode | codex — pass it explicitly
|
||||
SESSION_NAME=<workspace>-creator-<agent> # same convention as multi-agent-mux-create
|
||||
|
||||
# Resolve the isolated herdr server name & load common utils
|
||||
source .agents/skills/lib.sh
|
||||
|
||||
# 1. Resolve the session id (pass session name to prefer target-row recorded id)
|
||||
UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh \
|
||||
--workspace "$WORKSPACE" --agent "$AGENT" --session "$SESSION_NAME")
|
||||
|
||||
if [ -z "$UUID" ]; then
|
||||
case "$AGENT" in
|
||||
agy|hermes|opencode|codex)
|
||||
: # resume_session.sh handles fresh-spawn fallback automatically (FRESH_SPAWN=1)
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: No saved session for $WORKSPACE ($AGENT). Use multi-agent-mux-create first." >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
export HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME" "$WORKSPACE")"
|
||||
export MAM_WS_LABEL="${HERDR_WORKSPACE_OPT:-$(resolve_herdr_workspace "$SESSION_NAME" "$WORKSPACE")}"
|
||||
|
||||
# 2. If herdr is alive, attach. Done.
|
||||
if herdr has-session -t "$SESSION_NAME" 2>/dev/null; then
|
||||
echo "herdr '$SESSION_NAME' already running. Attaching..."
|
||||
exec herdr agent attach "$SESSION_NAME"
|
||||
fi
|
||||
|
||||
# 3. Determine CMD_FULL
|
||||
# For claude: if assigned UUID transcript .jsonl is unmaterialized on disk, use --session-id <uuid>; otherwise use -r <uuid>
|
||||
case "$AGENT" in
|
||||
claude) CMD_FULL="claude --dangerously-skip-permissions $CLAUDE_ID_FLAG $UUID" ;;
|
||||
agy) CMD_FULL="agy --dangerously-skip-permissions --conversation $UUID" ;;
|
||||
hermes) CMD_FULL="hermes --resume $UUID --no-restore-cwd --yolo --accept-hooks" ;;
|
||||
grok) CMD_FULL="grok --resume $UUID --permission-mode bypassPermissions" ;;
|
||||
opencode) CMD_FULL="opencode --session $UUID --auto --agent build" ;;
|
||||
codex) CMD_FULL="codex resume --dangerously-bypass-approvals-and-sandbox $UUID" ;;
|
||||
esac
|
||||
|
||||
# 4. Spawn new herdr session + run agent with the saved id
|
||||
eval "herdr new-session -d -s \"$SESSION_NAME\" -x 140 -y 40 -c \"$WORKSPACE\" \"$CMD_FULL\""
|
||||
# Issue #24: start-up dialogs (trust prompts, blocking notices) are answered for
|
||||
# every agent from the adapter's signatures - the same call create makes.
|
||||
# --no-auto-trust leaves a directory-trust dialog to a human (MAM_AUTO_TRUST=0).
|
||||
handle_startup_dialogs "$SESSION_NAME" 20 "$AGENT"
|
||||
|
||||
# 4. Update agent-sessions.yaml: status running, last_visible_status
|
||||
# (Also automatically publishes a `progress --detail "resumed"` event to the multi-agent-mux-delegate-job registry if a delegate_job_id exists)
|
||||
bash .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh \
|
||||
--session "$SESSION_NAME" --uuid "$UUID"
|
||||
|
||||
# 5. Attach (real native command — "attach" isn't in the lib.sh tmux-compat shim,
|
||||
# and real herdr has no `-t` flag here, only a positional target)
|
||||
herdr agent attach "$SESSION_NAME"
|
||||
bash .agents/skills/multi-agent-mux-resume/scripts/resume_session.sh --workspace <path> --agent <agent> --session <name>
|
||||
```
|
||||
|
||||
`resume_session.sh` does the whole flow: original-cwd check, control-plane binding, session-id resolution (`resolve_session_id.sh`), the herdr-alive check, the agent command (adapter `resume-spec`, or `spawn-spec` for a Class A fresh spawn), spawn, start-up dialogs, and the YAML update (`update_yaml_resumed.sh`, which also publishes a `progress "resumed"` event when the row has a `delegate_job_id`). It never attaches; attaching is a separate step: `herdr agent attach <name>`.
|
||||
|
||||
| Option | Meaning |
|
||||
|---|---|
|
||||
| `--workspace` | Required. The directory the session ran in (its row's `pane.cwd`; a different path is exit 2) |
|
||||
| `--agent` | Required. `claude`, `agy`, `hermes`, `grok`, `opencode`, `codex` |
|
||||
| `--session` | Required. Session name |
|
||||
| `--herdr-session` (`--herdr-server`) | Isolated herdr server name |
|
||||
| `--herdr-workspace` | herdr workspace label |
|
||||
| `--auto-trust` / `--no-auto-trust` | Answer a start-up directory-trust dialog or leave it to a human (`MAM_AUTO_TRUST`; default: answer) |
|
||||
| `--dry-run` | Resolve the command and print it; write nothing |
|
||||
|
||||
| Exit | Meaning |
|
||||
|---|---|
|
||||
| 0 | Resumed; or already running, so only the row was updated (no attach); or `--dry-run` |
|
||||
| 1 | From the checks before spawn, nothing was changed: no saved session for claude/grok (use `multi-agent-mux-create` first), agent binary missing or not executable. **The YAML update after spawn (`update_yaml_resumed.sh`) also exits 1** (YAML not found) |
|
||||
| 2 | From the checks before spawn, nothing was changed: bad arguments, `--workspace` differs from the original cwd or it no longer exists, control-plane binding refused, whitespace in the control-plane path. **The YAML update after spawn also exits 2** (bad arguments) |
|
||||
| other | A later step failed (herdr spawn, start-up dialogs, YAML update) and its code is passed through. resume does not roll back |
|
||||
|
||||
A non-zero exit after the spawn can leave the herdr session running while the row is still `stopped`. Before retrying or creating a new session, check with `multi-agent-mux-status`. The `ERROR:` line on stderr tells the two apart: the pre-spawn checks' messages are in `resume_session.sh` (lines 50-223).
|
||||
|
||||
## Original cwd only (Issue #21 phase 2)
|
||||
|
||||
A session is resumed only in the directory it ran in (its row's `pane.cwd`): the conversation is keyed by that directory, and a class A agent (agy/hermes/opencode/codex) would otherwise start a new conversation in the wrong tree.
|
||||
@@ -130,7 +94,7 @@ A session is resumed only in the directory it ran in (its row's `pane.cwd`): the
|
||||
|
||||
- **`claude -r` requires the SAME project directory** — if the workspace path differs from when the session was created, claude will create a new project dir key (`-home-...-different-name`) and put the resume in a different location. Always `-c` (cd to workspace) before running.
|
||||
- **agy's `--conversation` flag name varies by version** — older versions used `--resume` or `-r`. Check `agy --help | grep -E "conversation|resume"` and use the right flag. v1.0.x: `--conversation`.
|
||||
- **The first message after resume might re-trigger TUI dialogs** — if the original session was created with `--dangerously-skip-permissions`, those flags are NOT persisted; you must re-apply them on resume. The script above re-passes them.
|
||||
- **The first message after resume might re-trigger TUI dialogs** — if the original session was created with `--dangerously-skip-permissions`, those flags are NOT persisted; you must re-apply them on resume. `resume_session.sh` re-passes them through the adapter `resume-spec`.
|
||||
- **Don't resume if the session is brand new and empty** — `multi-agent-mux-create` already set up an empty container; sending a probe message ("init") is the right way to materialize a session id, NOT `claude -r` with a placeholder.
|
||||
- **`agy --conversation <id>` will fail if the conversation was deleted from disk** — check `~/.gemini/antigravity-cli/conversations/<uuid>.db` exists before attempting resume. If missing, the conversation is gone; you need a fresh session via `multi-agent-mux-create`.
|
||||
|
||||
@@ -159,10 +123,10 @@ herdr agent read "$SESSION_NAME" --source visible --lines 30
|
||||
# look for the previous message at top of the buffer (claude) or last_visible_status set (agy)
|
||||
```
|
||||
|
||||
> `herdr list-panes` / `herdr capture-pane` here are tmux-compat pseudo-commands that only
|
||||
> work after `source .agents/skills/lib.sh` (as done in `Workflow` above) — the real `herdr`
|
||||
> binary doesn't have those subcommands. This block uses the real `herdr agent get`/`herdr agent read`
|
||||
> equivalents instead so it also works standalone.
|
||||
> `herdr list-panes` / `herdr capture-pane` are tmux-compat pseudo-commands that only
|
||||
> work after `source .agents/skills/lib.sh` — the real `herdr` binary doesn't have those
|
||||
> subcommands. This block uses only the real `herdr agent get`/`herdr agent read` commands,
|
||||
> so it works standalone.
|
||||
|
||||
## When NOT to use this skill
|
||||
|
||||
|
||||
@@ -73,31 +73,40 @@ lab-paper-pdf2md-creator-claude default running alive clau
|
||||
|
||||
```json
|
||||
{
|
||||
"yaml_path": "...",
|
||||
"herdr_sessions_alive": ["..."],
|
||||
"yaml_entries": [...],
|
||||
"rows": [
|
||||
"timestamp": "2026-06-19T14:20:00Z",
|
||||
"yaml_path": ".../.mam/agent-sessions.yaml",
|
||||
"herdr_sessions_alive": ["lab-landing-page-creator-claude|default"],
|
||||
"herdr_confirmed": true,
|
||||
"drifts": [
|
||||
{"class": "A", "name": "lab-landing-page-creator-agy", "msg": "..."}
|
||||
],
|
||||
"actions": [],
|
||||
"sessions_detail": [
|
||||
{
|
||||
"name": "lab-landing-page-creator-claude",
|
||||
"yaml_status": "running",
|
||||
"server": "default",
|
||||
"herdr_workspace": "landing-page",
|
||||
"status": "running",
|
||||
"herdr_alive": true,
|
||||
"pane_cmd": "claude",
|
||||
"cmd": "claude",
|
||||
"role": "creator",
|
||||
"resume_state": "yes",
|
||||
"job_id": null,
|
||||
"job_status": null,
|
||||
"pane_cwd": "/home/.../refer_landing_page",
|
||||
"resume_uuid_on_disk": true,
|
||||
"drift": null
|
||||
},
|
||||
{
|
||||
"name": "lab-landing-page-creator-agy",
|
||||
"yaml_status": "terminated",
|
||||
"herdr_alive": false,
|
||||
"drift": "yaml-says-terminated-but-disk-uuid-still-present"
|
||||
"attach_command": "HERDR_SESSION_NAME=default herdr agent attach lab-landing-page-creator-claude",
|
||||
"drift_classes": [],
|
||||
"pane_pid": 12345,
|
||||
"cmd_full": "claude --dangerously-skip-permissions --session-id <uuid>",
|
||||
"start_command": "...",
|
||||
"last_visible_status": "pinned"
|
||||
}
|
||||
],
|
||||
"unregistered": [],
|
||||
"drifts": []
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The top-level keys other than `sessions_detail` are `reconcile.sh --once --emit-diff --dry-run`'s output, passed through unchanged. `resume_state` is `yes`, `MISSING`, `scan` or `no`.
|
||||
|
||||
## Drift classes (read-only — never mutates)
|
||||
|
||||
| Class | Detection | Meaning |
|
||||
|
||||
@@ -35,32 +35,7 @@ The stop command is always **graceful by default**:
|
||||
|
||||
## Pre-flight
|
||||
|
||||
```bash
|
||||
SESSION_NAME=<workspace>-creator-<agent> # convention
|
||||
AGENT=claude # claude | agy | hermes | grok | opencode | codex — always pass it
|
||||
AGENT_SESSIONS_YAML=.mam/agent-sessions.yaml
|
||||
|
||||
# 1) Session is registered?
|
||||
python3 -c "
|
||||
import yaml
|
||||
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
|
||||
names = [s['name'] for s in d.get('herdr_sessions', [])]
|
||||
if '$SESSION_NAME' not in names:
|
||||
print('NOT in YAML — refusing to stop (no audit trail). Use multi-agent-mux-create first, or pass --force-no-yaml.')
|
||||
raise SystemExit(1)
|
||||
"
|
||||
|
||||
# 2) Already stopped?
|
||||
ALREADY=$(python3 -c "
|
||||
import yaml
|
||||
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
|
||||
s = [x for x in d['herdr_sessions'] if x['name']=='$SESSION_NAME'][0]
|
||||
print(s.get('status', 'unknown'))
|
||||
")
|
||||
if [ "$ALREADY" = "stopped" ]; then
|
||||
echo "Already stopped."
|
||||
fi
|
||||
```
|
||||
`stop_session.sh` checks this itself: the YAML exists and the session is registered (otherwise exit 1), and a session already `stopped` is a no-op (exit 0).
|
||||
|
||||
## Workflow
|
||||
|
||||
@@ -76,9 +51,22 @@ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
|
||||
# 3. Stop gracefully + clean up on-disk conversation (DANGEROUS)
|
||||
# — this prevents any future resume (status=terminated, resumable=false).
|
||||
bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
|
||||
--session "$SESSION_NAME" --agent "$AGENT" --purge-conversation
|
||||
--session "$SESSION_NAME" --agent "$AGENT" --purge-conversation --yes
|
||||
```
|
||||
|
||||
`--purge-conversation` cannot be undone. Pass `--yes` only after the user has confirmed it.
|
||||
|
||||
| Exit | Meaning |
|
||||
|---|---|
|
||||
| 0 | Stopped; or already `stopped` (no-op) |
|
||||
| 1 | YAML not found, or the session is not registered |
|
||||
| 2 | Bad arguments (including the retired `--mode` / `--capture-id` / `--graceful`), or `--agent` omitted and not resolvable |
|
||||
| 3 | `--purge-conversation` without `--yes` |
|
||||
| 4 | Purge aborted: the herdr session survived the kill chain |
|
||||
| other | The registry update after the stop (YAML / DB write) failed and its code is passed through |
|
||||
|
||||
Exits 1, 2 and 3 come from checks before anything is stopped, so nothing was changed. On an `other` exit the session may already be down while its row still says `running`: check with `multi-agent-mux-status`, then run the stop again (it is idempotent).
|
||||
|
||||
**Idempotency**: if the row is already `status: stopped`, the script prints `already stopped (...)` and exits 0 — re-running is a safe no-op.
|
||||
|
||||
**`--agent` is the standard.** Pass it on every invocation. If omitted, the script
|
||||
|
||||
Reference in new issue
Block a user