@muggleai/works 5.9.0 → 5.11.0

package/plugin/skills/_shared/post-merge-cleanup.md

@@ -4,6 +4,86 @@ Gated by [`autoCleanup`](../muggle-preferences/preference-gates/autoCleanup.md).
 
 On `always`, the steps below run as one pre-authorized sequence (no per-step prompts). Stop on the first failure; do not force.
 
-1. **Remove the worktree — link-safe.** `git worktree remove {worktreePath}`, only if a worktree was used. A worktree's dependency dir (e.g. `node_modules`) is often a **link** (symlink, or a Windows junction) to a shared tree, not a real copy — and a forced/recursive delete follows the link and wipes that shared target, breaking every worktree. So never `--force`: unlink the dependency link first (remove the link only, using the host OS's unlink), then a plain `git worktree remove {worktreePath}`.
-2. `git branch -d {branch}` — **skip when no worktree was used**: the branch is the user's current live checkout (a bootstrap/auto-track watcher), and the checked-out branch must never be deleted. Then `git push origin --delete {branch}`.
-3. Clear `.muggle-ai/` session folders for this branch's runs and stale `/tmp/muggle-prepare-*.log` files. Cloud results stay.
+**Verify every step, assume none.** Each step states what proves it succeeded. A step whose side effect *usually* happens is not a step that ran — that assumption is how a branch survives a cleanup that reported success. The [report](#report) states verified state, never intent.
+
+## Preconditions
+
+Confirm the PR is `MERGED` from provider state. A closed-unmerged PR keeps its branch and worktree: the work never landed, so deleting it destroys it.
+
+## 1. Remove the worktree — link-safe
+
+Only if a worktree was used.
+
+A worktree's dependency dir (`node_modules`, and nested workspace copies) is often a **link** — a symlink or a Windows junction — to a shared tree rather than a real copy. A forced or recursive delete follows the link and wipes that shared target, breaking every other worktree.
+
+1. **Never `--force`.** It is the one flag that follows links.
+2. Clear the dependency and build dirs first, nested workspace ones included (`packages/*/node_modules`, `dist`). A plain `git worktree remove` fails with `Directory not empty` while they remain, and the obvious fix for that error is exactly the forbidden flag.
+   - A **link** → unlink it first with the host OS's unlink, removing the link only and never its target.
+   - A **real directory** → delete it in place.
+   Check which it is before deleting; the two are indistinguishable from a listing but not from a `rm -r`.
+3. Then plain `git worktree remove {worktreePath}`.
+4. `git worktree prune` to drop the administrative entry when the directory went away out from under git.
+
+**Verify:** the path is gone, it no longer appears in `git worktree list`, **and** the shared dependency tree the links pointed at still exists. That last check is the one that catches a link-follow.
+
+## 2. Delete the local branch
+
+**Skip entirely when no worktree was used** — the branch is then the user's live checkout, and a checked-out branch must never be deleted.
+
+`git branch -d` refuses after a **squash merge**, and always will: squashing mints a new commit carrying the same tree, so the branch tip is never an ancestor of the base. This is not a safety check that failed; it is one that cannot pass.
+
+Do not reach for `-D` on faith. Replace the ancestry check with a content check:
+
+1. Confirm the merged content is on the base — files the PR added exist at `origin/<base>`, and anything it removed is absent there.
+2. Only then `git branch -D {branch}`.
+
+**Verify:** the branch is absent from `git branch --list`.
+
+## 3. Delete the remote branch
+
+**A provider that auto-deletes the head branch on merge is a setting, not a guarantee.** It can be off for the repo, off for a fork, or simply not fire. Treat auto-delete as something to detect, never as this step having run.
+
+1. Query the ref. Already gone → record it deleted and move on.
+2. Still present → delete it explicitly.
+
+**Verify:** querying the ref returns not-found.
+
+## 4. Clear the session slot
+
+The slot is `~/.muggle-ai/muggle-do/sessions/<slug>/` — the home directory, not the project.
+
+Clear it only when `prs.json` records a terminal state. A slot for a still-open PR is live state that a watcher and [`reconcile`](../muggle-pr-followup/reconcile.md) both read. The merged PR is the durable record, so the slot's `result.md` is not lost history.
+
+**Verify:** the slot directory is gone, and no non-terminal slot was touched.
+
+## 5. Clear this run's prepare artifacts
+
+The PID tracker and per-service logs written during environment prep — `/tmp/muggle-test-prepare.json` and `/tmp/muggle-prepare-*.log`.
+
+**Only this run's.** Artifacts belonging to another session are not yours to delete; it may be mid-prepare with services running. When the tracker is absent no services are tracked, so any remaining logs are orphaned — report them rather than removing them.
+
+Cloud results always stay.
+
+**Verify:** this run's artifacts are gone; anything left is named in the report as out of scope.
+
+## Report
+
+Print as the last action, one row per step, filled from the verification checks — never from the fact that a command was issued:
+
+```
+Cleanup — <slug> (PR #<n>, merged)
+
+| Step                  | Result                                          |
+|:----------------------|:------------------------------------------------|
+| Worktree removed      | ✅ .claude/worktrees/<name> (shared deps intact) |
+| Local branch deleted  | ✅ users/<user>/<branch>                         |
+| Remote branch deleted | ✅ (already gone — provider auto-delete)         |
+| Session slot cleared  | ✅ <slug>                                        |
+| Prepare artifacts     | — none for this run                              |
+```
+
+Markers: `✅` verified done · `⚠️` done with a caveat worth reading · `❌` not done, with the reason · `—` nothing to do.
+
+Every step gets a row. A step that did not run is `❌` plus its reason — never omitted, and never `✅` when its verification did not actually run. A silent gap is worse than a visible one, because it is the version the user ends up believing.
+
+State anything deliberately left alone — another session's artifacts, a foreign worktree, an orphaned watcher — on a line below the table, so out-of-scope is declared rather than invisible.

package/plugin/skills/_shared/pr-followup-helpers/loop-signature.md

@@ -1,22 +1,20 @@
 # Loop comment signature
 
-Every GitHub comment `/muggle-do` posts — inline thread replies, top-level reference comments, resolve-reminders — **must** end with the signature block below. It is the only reliable way to tell loop-authored comments from human comments: in single-account workflows the loop posts under the PR author's own identity, so `author.login` cannot distinguish them. Echo-protection and addressed-by-loop classification both depend on this marker.
+Every comment `/muggle-do` posts on either provider — inline thread replies (`gitlab`: discussion notes), top-level reference comments, resolve-reminders — **must** carry the loop marker. It is the only reliable way to tell loop-authored comments from human comments: in single-account workflows the loop posts under the change author's own identity, so the author login cannot distinguish them. Echo-protection and addressed-by-loop classification both depend on this marker.
 
-## The signature
-
-Append these two lines as the end of every loop-posted comment body:
+## The marker
 
 ```
 <!-- muggle-do:bot -->
-🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
 ```
 
-- `<!-- muggle-do:bot -->` — hidden HTML marker; GitHub renders it invisibly and humans never type it. This is the **detection token**. It must stay exactly as written — echo-protection and addressed-by-loop classification read this literal string.
-- The visible line is the shared Muggle Works signature ([`../vcs/post-signature.md`](../vcs/post-signature.md)) with `/muggle-do` as the command. It links a reader back to the tool and names the command that posted the comment.
+Hidden HTML: both providers render it invisibly and humans never type it. It must stay exactly as written — echo-protection and addressed-by-loop classification read this literal string.
+
+Signing a body with `--mode loop` ([`../vcs/post-signature.md`](../vcs/post-signature.md)) emits the marker above the visible Muggle Works line. Never hand-write either one; a body assembled by hand is the one that silently ships without them.
 
 ## Detection
 
 - **Loop-authored** — the comment body contains the literal `<!-- muggle-do:bot -->`.
 - **Human** — the body does not contain the marker.
 
-Classify by the marker, never by `author.login` alone — the login is ambiguous under a shared account. A comment that carries the marker is the loop's own and must never re-trigger a cycle; a comment without it is human intent to act on.
+Classify by the marker, never by the author login alone (`github`: `author.login`, `gitlab`: `author.username`) — the login is ambiguous under a shared account. A comment that carries the marker is the loop's own and must never re-trigger a cycle; a comment without it is human intent to act on.

package/plugin/skills/_shared/pr-followup-helpers/reply-routing.md

@@ -1,32 +1,24 @@
 # Reply routing
 
-GitHub's PR APIs are not uniform across comment types. Route by parent type.
+Reply endpoints are not uniform across comment types. Route by parent type, then run the resolved provider's recipe for that route — resolve the provider once per [`../vcs/detect-vcs.md`](../vcs/detect-vcs.md). The routing decision below is provider-agnostic; the commands live with their tool.
 
 ## Line-level review comment (most common)
 
-A comment attached to a specific file:line that belongs to a review thread.
+A comment attached to a specific file:line that belongs to a review thread. Reply in the same thread, so the reply keeps its context:
 
-```bash
-gh api \
-  --method POST \
-  -H "Accept: application/vnd.github+json" \
-  /repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies \
-  -f body="Done in $(git rev-parse --short HEAD) — renamed \`fooBar\` to \`foo_bar\`."
-```
-
-The reply lands in the same review thread with `in_reply_to_id = <comment_id>`.
+- `github` — [`../vcs/github/reply-line-comment.md`](../vcs/github/reply-line-comment.md). The reply lands in the thread with `in_reply_to_id = <comment_id>`.
+- `gitlab` — [`../vcs/gitlab/reply-discussion.md`](../vcs/gitlab/reply-discussion.md). The reply is a new note on the discussion.
 
-## Review body (CHANGES_REQUESTED with no inline comments)
+## Review body with no inline comments
 
-A reviewer left a summary review with `state: CHANGES_REQUESTED` and a body, but **no** inline comments. GitHub has no "reply to review body" endpoint — post a top-level PR comment that references the review:
+A reviewer left a summary review with a body but **no** inline comments. There is no thread to reply into, so answer with a top-level comment that names the review:
 
-```bash
-gh pr comment <number> --repo <owner>/<repo> --body "Re: review #<review_id> — done in $(git rev-parse --short HEAD)."
-```
+- `github` — [`../vcs/github/top-level-comment.md`](../vcs/github/top-level-comment.md). GitHub has no reply-to-review-body endpoint, which is why this route exists at all.
+- `gitlab` — does not arise. GitLab has no review envelope; every note belongs to a discussion, so it routes as a line-level reply above.
 
 ## Failing CI check
 
-No reply. The fix commit IS the response. Include the failing check name in the commit subject:
+No reply on either provider. The fix commit IS the response. Include the failing check name in the commit subject:
 
 ```
 fix(ci): typecheck — narrow type of foo
@@ -36,5 +28,5 @@ fix(ci): lint — remove unused import
 ## Never
 
 - Never post a top-level comment in reply to a line-level comment. It loses thread context.
-- Never `gh pr review --comment` for replies — that endpoint is for *new* reviews.
+- Never open a *new* review to carry a reply (`github`: `gh pr review --comment`) — those endpoints are for new reviews, not replies.
 - Never reply twice to the same comment. The loop marker on each posted reply is the re-entry guard — a thread whose newest comment is loop-marked is no longer actionable, so the next round won't re-reply.

package/plugin/skills/_shared/resolve-e2e-validation-context.md

@@ -25,6 +25,7 @@ Resolve without prompting; use as questionnaire defaults:
 3. Candidate projects — `muggle-remote-project-list`, ranked against the repo's dev URL and the PR title.
 4. Existing test-user secrets — `muggle-remote-secret-list` per candidate project (`managed_profile_email` / `managed_profile_password`).
 5. Auth0 tenant for local dev — grep the repo env file for `*AUTH0_DOMAIN*`.
+6. E2E run instructions — read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists, keyed on this stack's identity. It records startup order, manual steps, and local gotchas. Treat it as read-only input: surface its gotchas rather than re-deriving them, and never re-ask what it already answers. Absent is normal — proceed without it.
 
 ## Questions
 

package/plugin/skills/_shared/vcs/CLAUDE.md

@@ -5,6 +5,7 @@ Provider-agnostic seam for the watcher and dev-cycle skills. A caller resolves o
 ## Index
 
 - [`detect-vcs.md`](detect-vcs.md) — resolve `github` | `gitlab` from a URL argument or the origin remote.
+- [`post-signature.md`](post-signature.md) — sign every posted body through `scripts/sign-body.sh`; provider-agnostic, required by every recipe below that writes a body.
 - [`github.md`](github.md) — `gh` / `git` recipe TOC; per-recipe files in [`github/`](github/).
 - [`gitlab.md`](gitlab.md) — `glab` / `git` recipe TOC; per-recipe files in [`gitlab/`](gitlab/).
 - `common/` — provider-agnostic entry points (`ci-rollup`, `branch-standing`, `push-to-branch`, `verify-working-tree`), indexed by both provider TOCs.

package/plugin/skills/_shared/vcs/github/pr-edit.md

@@ -3,8 +3,9 @@
 For `open-prs/update.md` when E2E state flips (passing↔failing) or validation strategy changes.
 
 ```bash
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-do --mode editable < <draft-file> > <signed-file>
 gh pr edit <pr-number> --repo <owner>/<repo> --title "<new-title>"
-gh pr edit <pr-number> --repo <owner>/<repo> --body-file <file>
+gh pr edit <pr-number> --repo <owner>/<repo> --body-file <signed-file>
 ```
 
-The `<file>` body must end with the Muggle Works signature. Because the description is re-posted on each refresh, strip the old signature (from the `<!-- muggle-works:signature -->` marker to the end) before re-appending it — see [`../post-signature.md`](../post-signature.md).
+Sign with `--mode editable` per [`../post-signature.md`](../post-signature.md) — a description is re-posted on every refresh, and that mode cuts the previous signature before appending so they never stack.

package/plugin/skills/_shared/vcs/github/reply-line-comment.md

@@ -3,10 +3,11 @@
 Used by `/muggle-do` per-comment inline replies.
 
 ```bash
+body="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-do --mode loop < <draft-file>)"
 gh api --method POST \
   -H "Accept: application/vnd.github+json" \
   repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies \
-  -f body="<reply-text>"
+  -f body="$body"
 ```
 
-The `<reply-text>` must end with the loop signature block — the `<!-- muggle-do:bot -->` detection marker above the Muggle Works line. See [`../post-signature.md`](../post-signature.md).
+Sign with `--mode loop` per [`../post-signature.md`](../post-signature.md) — the `<!-- muggle-do:bot -->` marker it prefixes is what keeps the loop from re-triggering on its own reply.

package/plugin/skills/_shared/vcs/github/top-level-comment.md

@@ -3,7 +3,8 @@
 For the resolve-reminder stage and any non-threaded notice.
 
 ```bash
-gh pr comment <pr-number> --repo <owner>/<repo> --body "<text>"
+body="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command <command> --mode <mode> < <draft-file>)"
+gh pr comment <pr-number> --repo <owner>/<repo> --body "$body"
 ```
 
-The `<text>` you post must end with the Muggle Works signature — see [`../post-signature.md`](../post-signature.md).
+Sign per [`../post-signature.md`](../post-signature.md). A resolve-reminder takes `--mode loop`, so the loop recognises the reminder as its own on a later tick; a one-shot notice nothing needs to detect takes `--mode plain`.

package/plugin/skills/_shared/vcs/gitlab/mr-create.md

@@ -3,9 +3,12 @@
 For `open-prs`. Push the branch first (see [`../common/push-to-branch.md`](../common/push-to-branch.md)), then open the MR.
 
 ```bash
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-do --mode editable < <draft-file> > <signed-file>
 glab mr create -R <group>/<project> \
   --source-branch <branch> --target-branch <base> \
-  --title "<title>" --description "$(cat <file>)"
+  --title "<title>" --description "$(cat <signed-file>)"
 ```
 
+Sign with `--mode editable` per [`../post-signature.md`](../post-signature.md) — the description this opens the MR with is the same body `mr-edit.md` refreshes later, so it carries the dedup marker from the start.
+
 `glab` prints the created MR's URL on success — capture stdout and store the URL for handoff (the watcher seeds from it, the user gets the link).

package/plugin/skills/_shared/vcs/gitlab/mr-edit.md

@@ -3,6 +3,9 @@
 For `open-prs/update.md` when E2E state flips (passing↔failing) or validation strategy changes. GitLab calls the body the **description**.
 
 ```bash
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-do --mode editable < <draft-file> > <signed-file>
 glab mr update <iid> -R <group>/<project> --title "<new-title>"
-glab mr update <iid> -R <group>/<project> --description "$(cat <file>)"
+glab mr update <iid> -R <group>/<project> --description "$(cat <signed-file>)"
 ```
+
+Sign with `--mode editable` per [`../post-signature.md`](../post-signature.md) — a description is re-posted on every refresh, and that mode cuts the previous signature before appending so they never stack.

package/plugin/skills/_shared/vcs/gitlab/mr-note.md

@@ -3,5 +3,8 @@
 For the resolve-reminder stage and any non-threaded notice.
 
 ```bash
-glab mr note <iid> -R <group>/<project> -m "<text>"
+body="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command <command> --mode <mode> < <draft-file>)"
+glab mr note <iid> -R <group>/<project> -m "$body"
 ```
+
+Sign per [`../post-signature.md`](../post-signature.md). A resolve-reminder takes `--mode loop`, so the loop recognises the reminder as its own on a later tick; a one-shot notice nothing needs to detect takes `--mode plain`.

package/plugin/skills/_shared/vcs/gitlab/reply-discussion.md

@@ -3,7 +3,10 @@
 Used by `/muggle-do` per-comment inline replies. A threaded reply is a new note appended to an existing discussion.
 
 ```bash
+body="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-do --mode loop < <draft-file>)"
 glab api --method POST \
   projects/:id/merge_requests/<iid>/discussions/<discussion-id>/notes \
-  -f body="<reply-text>"
+  -f body="$body"
 ```
+
+Sign with `--mode loop` per [`../post-signature.md`](../post-signature.md) — the `<!-- muggle-do:bot -->` marker it prefixes is what keeps the loop from re-triggering on its own note.

package/plugin/skills/_shared/vcs/post-signature.md

@@ -2,14 +2,34 @@
 
 Every pull-request / merge-request body, comment, and review-thread reply that muggle works posts ends with a signature line. Under a single-account workflow the automation posts as the repo owner, so the signature is what tells a reader — and a reviewer — that the post came from Muggle Works and which command produced it.
 
+## Signing a body
+
+Pipe the body through the shipped script. Never retype the line from this doc: a signature derived from prose is dropped silently, and a post that lost it still succeeds, still looks right to the poster, and is indistinguishable from a human comment forever after.
+
+```bash
+body="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command <command> --mode <mode> < <draft-file>)"
+```
+
+`--mode` picks the marker that precedes the visible line:
+
+| Mode | Marker | Use for |
+|------|--------|---------|
+| `loop` | `<!-- muggle-do:bot -->` | Thread replies and resolve-reminders — anything the loop must later recognise as its own. |
+| `editable` | `<!-- muggle-works:signature -->` | PR/MR descriptions. The script cuts the previous signature before appending, so a description re-posted on every refresh keeps exactly one. |
+| `plain` | none | One-shot comments that nothing needs to detect later. |
+
+Signing is idempotent — an already-signed body is re-signed, not double-signed — so a body may be passed through on a refresh path without checking whether it carries a signature already.
+
 ## The line
 
-Append this as the last line of the posted body:
+What the script emits, recorded here so a reader can recognise it. The script is the definition:
 
 ```
 🤖 _Posted by `<command>` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
 ```
 
+## Naming the command
+
 `<command>` is the slash-command of the skill whose `gh` / `glab` call posts the body:
 
 - `/muggle-do` — PR/MR descriptions, per-comment thread replies, top-level reference replies, and resolve-reminders.
@@ -17,15 +37,6 @@ Append this as the last line of the posted body:
 
 Name the command that owns the post, not the one that generated the content. When the walkthrough hands its rendered block back for embedding (Mode B/C), the caller owns the post, so the caller's command is what the signature names.
 
-## Editable bodies (PR / MR description)
-
-A description is re-posted whenever state changes, so its signature must not stack. Precede the line with a hidden marker and treat the pair as one unit:
-
-```
-<!-- muggle-works:signature -->
-🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
-```
-
-Before writing an edited body, delete everything from the `<!-- muggle-works:signature -->` marker to the end of the body, then append the block fresh. This keeps exactly one signature no matter how many times the description is refreshed.
+## Enforcement
 
-A comment or reply is posted once and never edited, so it needs no dedup marker — append the line alone. A loop-authored reply already carries the `<!-- muggle-do:bot -->` detection marker (defined in loop-signature.md) directly above this line; that marker stays, and this line replaces the old visible text.
+`scripts/check-post-signatures.mjs` fails any recipe that posts a body without signing it, on every PR via the `post-signatures` CI job and locally via `pnpm run verify:signatures`.

package/plugin/skills/do/open-prs/forward.md

@@ -31,10 +31,10 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
    - `## Changes` — summary of what changed in this repo.
    - `## Validation` — one line: link to E2E report, `unit-only`, or `skip — <reason>`.
    - **Walkthrough block** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md); on skip, omit this block. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B and embed the returned `body` verbatim. No report → skip the block.
-   - **Signature** — end the body with the Muggle Works signature, editable-body form (the `<!-- muggle-works:signature -->` marker + line, command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). It is the last thing in the body, after the walkthrough block.
+   - **Signature** — write the assembled body to a file and sign it with `--command /muggle-do --mode editable` per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). The signature lands last, after the walkthrough block; `editable` is the mode a description carries so later refreshes replace it instead of stacking.
 
 4. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
-   - `github` → `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
+   - `github` → `gh pr create --title "..." --body-file <signed-file> --head <branch>`, passing the file signed in Step 3. Capture the PR URL and number.
    - `gitlab` → open the change via [`../../_shared/vcs/gitlab/mr-create.md`](../../_shared/vcs/gitlab/mr-create.md): `glab mr create --source-branch <branch> --target-branch <base> --title "..." --description "..."`. Capture the MR URL and iid.
 
 5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once using the provider resolved in Step 4 — `github` per [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md), `gitlab` per [`../../_shared/vcs/gitlab/mr-note.md`](../../_shared/vcs/gitlab/mr-note.md). End the posted body with the signature line (command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). Never post when `comment` is `null`.

package/plugin/skills/do/per-comment-replies.md

@@ -27,14 +27,7 @@ If a comment has no associated change in either source (e.g. the comment was a q
 
 For each comment id with a description, post the reply with the resolved provider:
 
-- **`github`** — nested reply on the line comment:
-
-  ```bash
-  gh api --method POST \
-    -H "Accept: application/vnd.github+json" \
-    repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies \
-    -f body="<reply-body>"
-  ```
+- **`github`** — nested reply on the line comment, one per actionable comment, per [`../_shared/vcs/github/reply-line-comment.md`](../_shared/vcs/github/reply-line-comment.md).
 
 - **`gitlab`** — one threaded note per actionable discussion per [`../_shared/vcs/gitlab/reply-discussion.md`](../_shared/vcs/gitlab/reply-discussion.md) (the discussion id stands in for the comment id), then resolve each fully-addressed thread per [`../_shared/vcs/gitlab/resolve-discussion.md`](../_shared/vcs/gitlab/resolve-discussion.md). The loop-marked reply is the addressed signal; the resolve is GitLab's equivalent of a reviewer closing the thread, which the loop can do directly. Resolving folds the discussion out of the next tick's actionable set, so no separate resolve-reminder nudge is needed for it.
 
@@ -42,12 +35,9 @@ Reply body uses the template in [`../muggle-pr-followup/output-templates/inline-
 
 ```
 Addressed in <short-sha>: <one-line summary of the change made for THIS comment>.
-
-<!-- muggle-do:bot -->
-🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
 ```
 
-`<short-sha>` is the first 7 chars of `new_sha`; the body must contain that substring so the resolve-reminder stage knows which push addressed the thread. The trailing signature block is mandatory — its `<!-- muggle-do:bot -->` marker is what identifies the reply as loop-authored (see [`../_shared/pr-followup-helpers/loop-signature.md`](../_shared/pr-followup-helpers/loop-signature.md)).
+`<short-sha>` is the first 7 chars of `new_sha`; the body must contain that substring so the resolve-reminder stage knows which push addressed the thread. Write the content only — the posting recipe signs it with `--mode loop`, which appends the `<!-- muggle-do:bot -->` marker that identifies the reply as loop-authored (see [`../_shared/pr-followup-helpers/loop-signature.md`](../_shared/pr-followup-helpers/loop-signature.md)).
 
 ### Step 3 — Handle review-body-only comments (GitHub only)
 
@@ -58,9 +48,6 @@ If an actionable review has a non-empty `body` and **zero** line comments, GitHu
 
 ```
 Re: review #<review_id> — addressed in <short-sha>: <one-line summary>.
-
-<!-- muggle-do:bot -->
-🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
 ```
 
 Posted per [`../_shared/vcs/github/top-level-comment.md`](../_shared/vcs/github/top-level-comment.md). Fires at most once per actionable review-with-no-line-comments. Does not fire if the review has line comments — Step 2 covers those.

package/plugin/skills/muggle/SKILL.md

@@ -12,7 +12,7 @@ Use this as the top-level Muggle Test command router.
 
 ## Preferences
 
-User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json` (global) → `<repo>/.muggle-ai/preferences.json` (project). Treat absent prefs as `ask`.
+User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. Treat absent prefs as `ask`.
 
 This router skill itself does not gate any decision on a preference — it just routes user intent to a downstream skill. Each downstream skill consults its own preferences. For example, `checkForUpdates` is consulted by `muggle-status` (Check 4), not here.
 

package/plugin/skills/muggle-browser-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-browser-task
-description: "Perform a real action on a website or web app from a plain-English instruction — log in and do the thing: submit a form, create or update a record, place an order, refund a charge, file a ticket, publish a post, click through and complete a multi-step flow (Stripe, Jira, Shopify, the AWS console, WordPress, LinkedIn, an admin dashboard). Use whenever the user wants something actually done in a web UI ('log into X and …', 'submit the form', 'create the ticket', 'refund the charge', 'place the order', 'update the listing'); Muggle drives a real browser to do it, so reach for this rather than declining or doing it by hand. Boundary: this performs the action (operating a site's own UI), not migrating personal data between consumer apps; to verify a flow works instead, use muggle-test-feature-local."
+description: "Perform a real action on a website or web app from a plain-English instruction — log in and do the thing: submit a form, create or update a record, send a message, place an order, refund a charge, file a ticket, publish a post, complete a multi-step flow. Muggle drives a real browser through the site's own UI and supplies the session — managed login profiles and stored credentials — so a named service (Slack, Jira, Stripe, WordPress, a marketplace, a booking site, an admin panel) is a signal to reach for this skill, not to hunt for its API or connector; \"no logged-in session\" is not a reason to decline. Use whenever the user wants something done in a web UI ('log into X and …', 'send the message', 'create the ticket'), rather than declining or doing it by hand; ask for missing specifics inside the flow, not instead of starting it. Boundary: this performs the action (operating a site's own UI), not migrating personal data between consumer apps; to verify a flow works instead, use muggle-test-feature-local."
 ---
 
 # Muggle Test Task Runner

package/plugin/skills/muggle-pr-followup/CLAUDE.md

@@ -13,7 +13,8 @@ This folder holds the watcher loop that drives one PR toward merge-ready. The wa
 - [`finalize.md`](finalize.md) — shared termination sequence for a terminal PR (mark terminal, `result.md`, log/telemetry, unschedule cron, post-merge cleanup handoff). Called by `contract.md` and `reconcile.md`.
 - [`cancel-cron.md`](cancel-cron.md) — stops this watcher's cron, recorded-id-first (survives `CronList` going blind) with a `CronList`-match fallback, plus the tool-call-not-shell guard. Referenced by `contract.md` and `finalize.md`.
 - [`record-cron-id.md`](record-cron-id.md) — the per-tick self-record that keeps this slot's cron id in `cron.json` deletable after a compaction blinds `CronList`. Referenced by `contract.md` Step 0.
-- [`reconcile.md`](reconcile.md) — sweep that finalizes slots whose PR went terminal while polling lapsed, deletes orphaned crons, and re-arms open slots whose watcher stopped silently (dropped respawn); runs on demand, at the top of auto-track, and nudged by a session-start hook.
+- [`reconcile.md`](reconcile.md) — sweep that finalizes slots whose PR went terminal while polling lapsed, deletes orphaned crons, and re-arms **this session's own** open slots whose watcher stopped silently (dropped respawn); reports slots owned by other sessions without touching them. Runs on demand, at the top of auto-track, and nudged by a session-start hook.
+- [`adopt.md`](adopt.md) — the user's explicit takeover of a slot owned by a session that is gone: claim `owner.json`, then arm. The only path by which a slot changes hands; nothing automatic calls it.
 - [`stop.md`](stop.md) — the owner's kill switch: tears down monitor + cron per slot, renames the slot to `<slug>.stopped` (invisible to every recovery path), and — for stop-everything — writes the global kill file; surviving orphaned crons arrive as one-line absorbs.
 - [`state-schemas.md`](state-schemas.md) — canonical JSON shapes of session state files.
 - [`output-templates.md`](output-templates.md) — TOC of message templates; per-group files in `output-templates/`.

package/plugin/skills/muggle-pr-followup/SKILL.md

@@ -20,7 +20,9 @@ A watcher that babysits one open PR toward **merge-ready** — review threads ad
 
 **Cron lifecycle.** Each tick records its `/loop` cron id to `cron.json` while `CronList` can still see it ([`record-cron-id.md`](record-cron-id.md)), so teardown can delete the cron by id after a session continue / compaction blinds `CronList` to it. Reconcile ([`reconcile.md`](reconcile.md)) sweeps crons whose PR is terminal or whose slot is gone, and re-arms an open slot whose watcher stopped silently — monitor-first, never with a recurring cron.
 
-**Session death.** Monitors and crons are both session-bound — a session that ends or hits its usage limit takes every watch with it. That is by design: nothing polls out of session, because a review is addressed only inside a session that carries the context to address it, never by a headless process replying context-blind. The recovery point is the **next session start** — the `reconcile-stale-watchers.sh` hook nudges [`reconcile`](reconcile.md#triggers), which re-arms every open slot whose watcher is dead. A review landing while no session runs waits until then.
+**Session death.** Monitors and crons are both session-bound — a session that ends or hits its usage limit takes every watch with it. That is by design: nothing polls out of session, because a review is addressed only inside a session that carries the context to address it, never by a headless process replying context-blind.
+
+**A watcher belongs to the session that armed it.** Each slot records its owning session in `owner.json` ([`state-schemas.md`](state-schemas.md#ownerjson)), and recovery is owner-scoped: [`reconcile`](reconcile.md#triggers) re-arms a dead watcher only inside the session that armed it, and reports the rest as orphans it declined to touch. Starting a session therefore picks up nothing new — the same context argument that rules out a headless daemon rules out inheriting a stranger's PR, which would hand review work to a session that never saw the design. A PR whose owning session is gone stays unwatched until the user adopts it by name ([`adopt.md`](adopt.md)).
 
 ## Routing
 
@@ -39,12 +41,13 @@ The skill recognizes its mode by inspecting `$ARGUMENTS` and falling back to on-
 | empty | — | **auto-track** → [`auto-track.md`](auto-track.md) |
 | `help` / `?` | — | **help:** list active loops per [`output-templates/help.md`](output-templates/help.md) |
 | `reconcile` / `sweep` (optional `<slug>`) | — | **reconcile** → [`reconcile.md`](reconcile.md) |
+| `adopt` (optional `<slug>`) | — | **adopt** → [`adopt.md`](adopt.md) — take over a slot owned by a dead session; no slug lists the adoptable ones |
 
 **`--wake=<event>`** is passed only by an event wake's dispatch ([`arm-watcher.md`](arm-watcher.md) step 5) — it asserts the monitor already saw something new, so the tick's poll is justified. Manual invocations never pass it; with a live watcher they get watch-status, because a poll that nothing prompted is a main-session poll wasted. Recovery fires need no flag — a recoverable slot's watcher is dead by definition, so the gate falls through to tick. A stale cron firing against a re-armed slot hits the live-`watch.pid` branch and is absorbed as a status line, no provider calls.
 
-Auto-track runs **reconcile** first, so a no-arg invocation also finalizes any slot whose PR merged or closed while its watcher was down (expired cron, ended session) and re-arms any open slot whose watcher stopped silently (a dropped respawn). Reconcile recovers a watcher that was already running; it never seeds a first watcher for a PR — that is auto-track's / bootstrap's job.
+Auto-track runs **reconcile** first, so a no-arg invocation also finalizes any slot whose PR merged or closed while its watcher was down (expired cron, ended session) and re-arms this session's own open slots whose watcher stopped silently (a dropped respawn). Reconcile recovers a watcher that was already running; it never seeds a first watcher for a PR — that is auto-track's / bootstrap's job — and never re-arms one this session does not own. A no-arg invocation is a request to track *your* PRs, so it can only ever end with the session watching PRs it pushed plus watchers it already had.
 
-**Reconcile also runs at session start** — a `SessionStart` hook ([`../../hooks/README.md`](../../hooks/README.md)) surfaces the sweep when open slots exist, catching a watcher that died with its session (end, or 7-day `/loop` expiry) before a manual sweep would. See [`reconcile.md`](reconcile.md#triggers).
+**Reconcile also runs at session start** — a `SessionStart` hook ([`../../hooks/README.md`](../../hooks/README.md)) surfaces the sweep when open slots exist, catching a watcher that died with its session (end, or 7-day `/loop` expiry) before a manual sweep would. It reports orphaned slots without acting on them; treat that report as inventory, never as a to-do. See [`reconcile.md`](reconcile.md#triggers).
 
 Bootstrap accepts three optional trailing flags:
 

package/plugin/skills/muggle-pr-followup/adopt.md

@@ -0,0 +1,60 @@
+# Adopt Procedure
+
+The procedure for the **adopt mode** of `muggle-pr-followup` — the user's deliberate takeover of a watcher slot owned by a session that is gone. Routing is in [`SKILL.md`](SKILL.md#routing).
+
+Adoption is the only way a slot changes hands. [`reconcile.md`](reconcile.md) re-arms watchers this session already owns and refuses everything else; this file is the door it refuses through. Both exist because a watcher polls a PR in order to hand review work to `/muggle-do` **inside the owning session** — the session that carries the design decisions, the reviewer's phrasing, and the reasoning behind the branch. A session adopting a PR takes that job on without any of it, so the user has to say so.
+
+## Input
+
+`$ARGUMENTS` is `adopt`, optionally followed by a `<slug>`.
+
+- **`adopt <slug>`** — take that slot.
+- **`adopt`** alone — list the adoptable slots and stop. It is a query, not a prompt: print the list and end the turn, with no `AskUserQuestion` and no arming. The user picks by running the command again with a slug.
+
+## Procedure
+
+### Step 1 — Resolve the slot
+
+Slot path is `~/.muggle-ai/muggle-do/sessions/<slug>/`. Refuse, one line each, when:
+
+- **The dir is missing** — `no slot for <slug>; pass a PR URL to start one`.
+- **The name ends in `.stopped`** — `<slug> was stopped by its owner; rename it back to adopt it`. Adoption is not a way around [`stop.md`](stop.md): the rename is the owner's kill switch, and honoring it here keeps that switch meaning one thing everywhere.
+- **`result.md` exists** — `<slug> is finalized (<state>); nothing to watch`.
+- **This session already owns it** — `<slug> is already owned by this session`, then run [`reconcile.md`](reconcile.md) scoped to that slug so a dead poller still gets recovered. Adopting what you own is a no-op, not an error.
+
+With no slug, list every adoptable slot — open, not `.stopped`, owned by another session or none — as `<slug> → <owner>/<repo>#<n> (owner: <session-id | none>)`, then stop.
+
+### Step 2 — Confirm the PR is still worth watching
+
+Fetch the PR per [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md) using `prs.json[0].url`.
+
+- `MERGED` / `CLOSED` → do not adopt. Run [`finalize.md`](finalize.md) on the slot instead and say so: the slot needed closing out, not a watcher.
+- `gh` fails → surface the error verbatim and stop. Never claim a slot whose PR cannot be read; the claim would strand it under a session that cannot poll it either.
+- `open` → continue.
+
+Refresh `prs.json[0].head_sha` to the current `headRefOid`. The branch has almost certainly moved since the original owner last looked.
+
+### Step 3 — Warn about the context gap
+
+State plainly, in one line, what adoption does not carry: `adopting <slug> — this session has none of the original session's context for #<n>; cycles will work from the PR and the diff alone.`
+
+This is a statement, not a gate — the user asked. It exists because the failure it describes is silent: an adopted watcher looks identical to one this session armed, and the first sign of the gap is usually a reply that misreads why the code is the way it is.
+
+### Step 4 — Claim and arm
+
+Write `owner.json` ([`state-schemas.md`](state-schemas.md#ownerjson)) with `session_id` from `$CLAUDE_CODE_SESSION_ID` and `claimed_at` now, overwriting any previous owner. If `$CLAUDE_CODE_SESSION_ID` is unset, stop with `cannot adopt: no session id to record` — an unidentifiable owner leaves the slot recoverable by nobody.
+
+Then arm per [`arm-watcher.md`](arm-watcher.md): one drain tick, then the persistent monitor. The drain is what makes the adoption honest — it acts on everything outstanding now, rather than resuming from a watermark seeded against a wave the original session read and this one never saw.
+
+Append `adopted (from <previous-owner | unowned>)` to the slot's `followup.log`.
+
+### Step 5 — Report
+
+One line: `adopted <slug> → <owner>/<repo>#<n> — armed`.
+
+## Invariants
+
+- **Explicit only.** Adoption runs when the user names it. No sweep, hook, auto-track, or tick ever calls this procedure, and nothing offers it unprompted.
+- **One slot per invocation.** No bulk adopt, no `--all`. Adopting every orphan in one command is the behavior the ownership gate exists to prevent, wearing a different name.
+- **Stopped stays stopped.** A `.stopped` slot is unreachable here, as it is from every other recovery path.
+- **Claim before arm.** `owner.json` is written before the monitor starts, so a crash between the two leaves a slot this session owns and can recover — never an armed watcher no session claims.