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>

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

@@ -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