@muggleai/works 5.10.0 → 5.11.0

package/dist/plugin/scripts/pr-watch-guards.sh

@@ -18,11 +18,14 @@
 #                           on its own; reconcile re-arms an open PR inside a live
 #                           session.
 
-MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-21600}"
+# Seconds a watch loop may live. 0 means unbounded — the `never` setting of the
+# watcherLifetime preference, which removes the only time-based reaper for a
+# loop whose session has gone. `watcher_superseded` is then the sole guard.
+MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-604800}"
 MUGGLE_PR_WATCH_POLL_INTERVAL="${MUGGLE_PR_WATCH_POLL_INTERVAL:-60}"
 # Consecutive failed fetches before a loop gives up. A watcher must ride through
 # a GitHub / network outage — an observed drop lasted ~8 minutes — not die and
-# leave the PR unwatched until the next session start. With the backoff below, 60
+# leave the PR unwatched until its owning session next starts. With the backoff, 60
 # spans hours; only a genuinely persistent unreachable slot (deleted repo,
 # revoked auth) exhausts it.
 MUGGLE_PR_WATCH_MAX_FETCH_FAILURES="${MUGGLE_PR_WATCH_MAX_FETCH_FAILURES:-60}"
@@ -50,6 +53,9 @@ watcher_superseded() {
 
 watcher_lifetime_exceeded() {
     local started="$1" now="$2" max="${3:-$MUGGLE_PR_WATCH_MAX_LIFETIME}"
+    # 0 is unbounded, not "already expired" — the arithmetic below would other-
+    # wise make every loop exit on its first iteration.
+    [ "$max" -eq 0 ] 2>/dev/null && return 1
     [ $((now - started)) -ge "$max" ]
 }
 

package/dist/plugin/scripts/pr-watch-loop.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+
+# The muggle-pr-followup watch loop. One process per PR slot: polls provider
+# state, prints one line per new event, and exits when the PR goes terminal.
+#
+# Ships as a file so arming runs it rather than rewrites it. A loop re-derived
+# from prose on every arm drifts — the behind-base wake went missing from half
+# the slots on one machine that way, leaving PRs unmergeable under watchers that
+# looked healthy. The wake conditions live in pr-watch-events.sh; this file is
+# the I/O around them.
+#
+# Usage: pr-watch-loop.sh --slot <dir> --repo <owner/name> --pr <n> --base <branch>
+
+set -uo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+slot=""
+repo=""
+pr_number=""
+base_branch="master"
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --slot) slot="$2"; shift 2 ;;
+        --repo) repo="$2"; shift 2 ;;
+        --pr) pr_number="$2"; shift 2 ;;
+        --base) base_branch="$2"; shift 2 ;;
+        *) echo "pr-watch-loop: unknown argument $1" >&2; exit 2 ;;
+    esac
+done
+
+if [ -z "$slot" ] || [ -z "$repo" ] || [ -z "$pr_number" ]; then
+    echo "pr-watch-loop: --slot, --repo and --pr are required" >&2
+    exit 2
+fi
+
+# Resolved absolutely at arm time so they still load after the arming session is
+# gone. Guards missing means the plugin moved or upgraded underneath this loop —
+# a newer version's watcher owns the slot now, so step down rather than run on
+# without the supersede check.
+for lib in pr-watch-guards.sh pr-watch-events.sh; do
+    [ -f "${script_dir}/${lib}" ] || exit 0
+    # shellcheck source=/dev/null
+    . "${script_dir}/${lib}"
+done
+
+echo "$$" > "${slot}/watch.pid"
+started=$(date +%s)
+fails=0
+
+# In-memory floors, above the on-disk watermark. The watermark is advanced by
+# the session after it handles a wave; these stop the loop re-reporting an event
+# in the window before that write lands.
+floor_review=0
+floor_comment=0
+floor_threads=";"
+floor_ci_red=""
+floor_rebase=""
+floor_blocked_digest=""
+
+# Pin the token once: a detached loop can lose access to gh's OS keyring
+# mid-run, which surfaces as empty fetches rather than an error.
+pinned_token="$(gh auth token 2>/dev/null)"
+[ -n "$pinned_token" ] && export GH_TOKEN="$pinned_token"
+
+fetch_pr_state() {
+    gh api graphql -F owner="${repo%%/*}" -F name="${repo##*/}" -F number="$pr_number" -f query='
+query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      state
+      headRefOid
+      baseRefOid
+      mergeable
+      commits(last: 1) {
+        nodes {
+          commit {
+            statusCheckRollup {
+              contexts(first: 100) {
+                nodes {
+                  __typename
+                  ... on CheckRun { name status conclusion }
+                  ... on StatusContext { context state }
+                }
+              }
+            }
+          }
+        }
+      }
+      reviews(last: 20, states: [COMMENTED, APPROVED, CHANGES_REQUESTED, DISMISSED]) { nodes { databaseId } }
+      reviewThreads(first: 100) {
+        nodes {
+          id
+          isResolved
+          isOutdated
+          comments(last: 1) { nodes { databaseId pullRequestReview { state } } }
+        }
+      }
+    }
+  }
+}' --jq '
+.data.repository.pullRequest as $pr
+| (($pr.commits.nodes[0].commit.statusCheckRollup.contexts.nodes) // []) as $contexts
+| ($contexts | map(
+    if .__typename == "CheckRun"
+    then {name: .name, verdict: (if .status != "COMPLETED" then "PENDING" else (.conclusion // "NEUTRAL") end)}
+    else {name: .context, verdict: (.state // "PENDING")}
+    end)) as $checks
+| [
+    $pr.state,
+    $pr.headRefOid,
+    $pr.baseRefOid,
+    $pr.mergeable,
+    (([$pr.reviews.nodes[].databaseId] | max) // 0),
+    (([$pr.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[]
+       | select((.pullRequestReview.state // "SUBMITTED") != "PENDING") | .databaseId] | max) // 0),
+    ([$pr.reviewThreads.nodes[] | select(.isResolved == false) | select(.isOutdated == false)
+      | select((.comments.nodes[0].pullRequestReview.state // "SUBMITTED") != "PENDING") | .id] | join(";")),
+    ($checks | map(select(.verdict == "PENDING")) | length),
+    ($checks | map(select(.verdict == "FAILURE" or .verdict == "ERROR" or .verdict == "TIMED_OUT" or .verdict == "STARTUP_FAILURE")) | length),
+    ($checks | sort_by(.name) | map(.name + ":" + .verdict) | join(","))
+  ] | @tsv' 2>>"${slot}/watch-fetch.log"
+}
+
+# behind_by needs its own call — see watch_wake_rebase for why no field on the
+# PR carries it. Made only when the head/base pair moved, so the steady state
+# stays one request per iteration.
+fetch_behind_count() {
+    local head_sha="$1"
+    gh api "repos/${repo}/compare/${base_branch}...${head_sha}" --jq '.behind_by' 2>>"${slot}/watch-fetch.log"
+}
+
+read_watermark_value() {
+    local key="$1" line value=""
+    while IFS= read -r line || [ -n "$line" ]; do
+        line="${line%$'\r'}"
+        case "$line" in
+            "${key}="*)
+                value="${line#"${key}"=}"
+                value="${value%\"}"
+                value="${value#\"}"
+                ;;
+        esac
+    done < "${slot}/watch-watermark.env"
+    printf '%s' "$value"
+}
+
+while :; do
+    watcher_superseded "$slot" "$$" && exit 0
+    watcher_lifetime_exceeded "$started" "$(date +%s)" && exit 0
+    touch "${slot}/watch-heartbeat" 2>/dev/null
+
+    # No watermark yet means the arming session has not finished seeding. Wait
+    # rather than treat every floor as zero, which would fire the whole backlog.
+    if [ ! -f "${slot}/watch-watermark.env" ]; then
+        sleep "$MUGGLE_PR_WATCH_POLL_INTERVAL"
+        continue
+    fi
+
+    watermark_review=$(read_watermark_value REV)
+    watermark_comment=$(read_watermark_value COM)
+    watermark_threads=$(read_watermark_value THREADS)
+    watermark_ci_red=$(read_watermark_value CIRED)
+    watermark_rebase=$(read_watermark_value REBASED)
+    watermark_blocked_digest=$(read_watermark_value BLOCKED_CIDIGEST)
+
+    state_line=$(fetch_pr_state)
+    # One quick retry before counting a strike: a single flaky call should not
+    # advance the failure budget.
+    [ -z "$state_line" ] && { sleep 3; state_line=$(fetch_pr_state); }
+
+    if [ -z "$state_line" ]; then
+        fails=$((fails + 1))
+        echo "$(date -u +%FT%TZ) fetch empty (${fails}/${MUGGLE_PR_WATCH_MAX_FETCH_FAILURES})" >> "${slot}/watch-fetch.log"
+        if [ "$fails" -ge "$MUGGLE_PR_WATCH_MAX_FETCH_FAILURES" ]; then
+            echo "WATCH-FAIL pr=$pr_number ${fails} consecutive fetch failures — see watch-fetch.log"
+            exit 1
+        fi
+        sleep "$(watcher_fetch_backoff "$fails")"
+        continue
+    fi
+
+    mapfile -t state_fields < <(watch_split_state "$state_line")
+    pr_state="${state_fields[0]-}"
+    head_sha="${state_fields[1]-}"
+    base_sha="${state_fields[2]-}"
+    mergeable="${state_fields[3]-}"
+    latest_review="${state_fields[4]-}"
+    latest_comment="${state_fields[5]-}"
+    unresolved_threads="${state_fields[6]-}"
+    pending_checks="${state_fields[7]-}"
+    failed_checks="${state_fields[8]-}"
+    ci_digest="${state_fields[9]-}"
+
+    if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then
+        echo "TERMINAL pr=$pr_number state=$pr_state"
+        exit 0
+    fi
+
+    if [ "$pr_state" != "OPEN" ]; then
+        fails=$((fails + 1))
+        if [ "$fails" -ge "$MUGGLE_PR_WATCH_MAX_FETCH_FAILURES" ]; then
+            echo "WATCH-FAIL pr=$pr_number unreadable state after ${fails} tries"
+            exit 1
+        fi
+        sleep "$(watcher_fetch_backoff "$fails")"
+        continue
+    fi
+    fails=0
+
+    if watch_wake_review "$pr_number" "$latest_review" \
+        "$(( watermark_review > floor_review ? watermark_review : floor_review ))"; then
+        floor_review="$latest_review"
+    fi
+
+    if watch_wake_comment "$pr_number" "$latest_comment" \
+        "$(( watermark_comment > floor_comment ? watermark_comment : floor_comment ))"; then
+        floor_comment="$latest_comment"
+    fi
+
+    if [ -n "$unresolved_threads" ]; then
+        IFS=';' read -ra thread_ids <<< "$unresolved_threads"
+        for thread_id in "${thread_ids[@]}"; do
+            if watch_wake_thread "$pr_number" "$thread_id" "${watermark_threads};${floor_threads}"; then
+                floor_threads="${floor_threads}${thread_id};"
+            fi
+        done
+    fi
+
+    if watch_wake_ci_red "$pr_number" "$pending_checks" "$failed_checks" "$head_sha" \
+        "${floor_ci_red:-$watermark_ci_red}"; then
+        floor_ci_red="$head_sha"
+    fi
+
+    rebase_key="${head_sha}..${base_sha}"
+    if [ "$rebase_key" != "$watermark_rebase" ] && [ "$rebase_key" != "$floor_rebase" ]; then
+        behind_count=$(fetch_behind_count "$head_sha")
+        if watch_wake_rebase "$pr_number" "$mergeable" "$behind_count" "$rebase_key" ""; then
+            floor_rebase="$rebase_key"
+        fi
+    fi
+
+    # The tick owns clearing the block, and it may not run for a while. Holding
+    # the emitted digest stops the loop repeating itself every iteration in the
+    # meantime — the repeat nagging the design rules out — while a further move
+    # still wakes it.
+    if [ "$ci_digest" != "$floor_blocked_digest" ] \
+        && watch_wake_blocked_resume "$pr_number" "$ci_digest" "$watermark_blocked_digest"; then
+        floor_blocked_digest="$ci_digest"
+    fi
+
+    sleep "$MUGGLE_PR_WATCH_POLL_INTERVAL"
+done

package/dist/plugin/scripts/reconcile-stale-watchers.sh

@@ -2,13 +2,16 @@
 
 set -euo pipefail
 
-# muggle-pr-followup watchers are session-only crons — they die on session end
-# and on the 7-day /loop expiry, leaving open PRs with no live poller. Re-arming
-# needs CronCreate, a Claude tool a shell hook can't call, so this hook can't
-# recover a watcher itself. It nudges instead: on session start, if any open slot
-# exists, it tells the agent to run reconcile (which finalizes terminal slots and
-# re-arms silently-dead open watchers). A pure directory scan — no gh, no writes —
-# so it stays cheap enough to run on every session start.
+# muggle-pr-followup watchers are session-bound — they die on session end and on
+# the 7-day /loop expiry, leaving open PRs with no live poller. Re-arming needs
+# Claude tools a shell hook can't call, so this hook nudges rather than acts.
+#
+# The nudge is owner-scoped. Each slot records the session that armed it in
+# owner.json; only slots owned by THIS session are a recovery the agent should
+# run, because re-arming a stranger's PR would hand review work to a session with
+# no context for it. Slots owned by another session (or none) are reported as
+# orphans with the adopt command, never as work to pick up. A pure directory scan
+# — no gh, no writes — so it stays cheap enough for every session start.
 
 escape_for_json() {
     local s="$1"
@@ -20,31 +23,76 @@ escape_for_json() {
     printf '%s' "$s"
 }
 
-# A slot is a live-or-dead open watcher iff it has prs.json (a tracked PR) but no
-# result.md (not yet finalized). result.md is the terminal marker.
+# Extract the first "session_id": "..." from a JSON file or string. Deliberately
+# sed rather than jq: jq is not guaranteed present, and on Windows it appends CRLF
+# that makes an empty field compare non-empty.
+read_session_id() {
+    sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1 | tr -d '\r'
+}
+
+hook_payload=$(cat 2>/dev/null || true)
+current_session_id=$(printf '%s' "$hook_payload" | read_session_id /dev/stdin)
+
+# A slot is an open watcher iff it has prs.json (a tracked PR) and no result.md
+# (not yet finalized). A *.stopped dir is the owner's kill switch — it keeps its
+# prs.json, so the name check is the only thing that distinguishes a slot the
+# owner deliberately killed from one awaiting recovery. Counting those reports
+# stopped watchers back as work.
 sessions_dir="${HOME}/.muggle-ai/muggle-do/sessions"
-stale_count=0
+owned_count=0
+orphan_count=0
+first_orphan_slug=""
+
 if [ -d "$sessions_dir" ]; then
     for slot in "$sessions_dir"/*/; do
         [ -d "$slot" ] || continue
-        if [ -f "${slot}prs.json" ] && [ ! -f "${slot}result.md" ]; then
-            stale_count=$((stale_count + 1))
+        case "$slot" in *.stopped/) continue ;; esac
+        [ -f "${slot}prs.json" ] || continue
+        [ ! -f "${slot}result.md" ] || continue
+
+        slot_owner=""
+        if [ -f "${slot}owner.json" ]; then
+            slot_owner=$(read_session_id "${slot}owner.json")
+        fi
+
+        # Fail closed: an unidentifiable session owns nothing. Absent owner.json
+        # (legacy slot) is likewise foreign — never adopted by default.
+        if [ -n "$current_session_id" ] && [ "$slot_owner" = "$current_session_id" ]; then
+            owned_count=$((owned_count + 1))
+        else
+            orphan_count=$((orphan_count + 1))
+            if [ -z "$first_orphan_slug" ]; then
+                first_orphan_slug=$(basename "$slot")
+            fi
         fi
     done
 fi
 
-# Clean state: no open slots to reconcile → stay completely silent, never nudge.
-if [ "$stale_count" -eq 0 ]; then
+# Clean state: nothing of this session's to recover and no orphans → stay silent.
+if [ "$owned_count" -eq 0 ] && [ "$orphan_count" -eq 0 ]; then
     exit 0
 fi
 
-if [ "$stale_count" -eq 1 ]; then
-    slot_word="slot"
+if [ "$owned_count" -eq 1 ]; then
+    owned_word="watcher"
 else
-    slot_word="slots"
+    owned_word="watchers"
 fi
 
-context="muggle-pr-followup: ${stale_count} open watcher ${slot_word} found (a tracked PR with no result.md). Session-only watcher crons die on session end and after the 7-day /loop expiry, so these may have no live poller. Run \`/muggle:muggle-pr-followup reconcile\` to finalize any whose PR went terminal and re-arm silently-stopped open watchers. Reconcile is idempotent — it re-arms only genuinely dead watchers and stays quiet on the rest."
+if [ "$owned_count" -gt 0 ]; then
+    context="muggle-pr-followup: ${owned_count} open ${owned_word} owned by this session may have lost its poller. Run \`/muggle:muggle-pr-followup reconcile\` to finalize any whose PR went terminal and re-arm the silently-stopped ones. Reconcile is idempotent and re-arms only watchers this session armed itself."
+else
+    context="muggle-pr-followup: no watchers belong to this session — nothing to re-arm."
+fi
+
+if [ "$orphan_count" -gt 0 ]; then
+    if [ "$orphan_count" -eq 1 ]; then
+        orphan_word="slot is"
+    else
+        orphan_word="slots are"
+    fi
+    context="${context} ${orphan_count} open ${orphan_word} owned by other sessions; reconcile will finalize them if their PR already merged or closed, but will never re-arm them. Adopt one deliberately with \`/muggle:muggle-pr-followup adopt <slug>\` (e.g. ${first_orphan_slug}) only if the user asks — do not offer or adopt on your own."
+fi
 
 escaped_context=$(escape_for_json "$context")
 

package/dist/plugin/scripts/sign-body.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+#
+# Appends the Muggle Works signature to a body about to be posted to a PR/MR.
+#
+# Reads the unsigned body on stdin, writes the signed body on stdout:
+#
+#   sign-body.sh --command /muggle-do --mode loop < draft.md
+#
+# --command  slash-command of the skill whose post this is (owner of the post,
+#            not the producer of the content).
+# --mode     loop      thread replies and resolve-reminders: prefixes the
+#                      <!-- muggle-do:bot --> echo-detection marker.
+#            editable  PR/MR descriptions: prefixes the dedup marker, and cuts
+#                      any previous signature so refreshes never stack.
+#            plain     one-shot comments with no marker.
+#
+# Idempotent: an already-signed body is re-signed, not double-signed.
+
+set -euo pipefail
+
+readonly REPOSITORY_URL='https://github.com/multiplex-ai/muggle-ai-works'
+readonly SIGNATURE_PREFIX='🤖 _Posted by '
+readonly LOOP_MARKER='<!-- muggle-do:bot -->'
+readonly EDITABLE_MARKER='<!-- muggle-works:signature -->'
+
+usage() {
+  echo "usage: sign-body.sh --command <slash-command> --mode <loop|editable|plain>" >&2
+  exit 2
+}
+
+postedCommand=''
+signatureMode=''
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --command) postedCommand="${2-}"; shift 2 ;;
+    --mode) signatureMode="${2-}"; shift 2 ;;
+    -h|--help) usage ;;
+    *) echo "sign-body.sh: unknown argument '$1'" >&2; usage ;;
+  esac
+done
+
+[ -n "$postedCommand" ] || usage
+case "$signatureMode" in
+  loop|editable|plain) ;;
+  *) usage ;;
+esac
+
+# Cuts any signature the body already carries, so re-signing an edited body
+# replaces it instead of stacking a second one underneath.
+stripExistingSignature() {
+  awk -v editableMarker="$EDITABLE_MARKER" \
+      -v loopMarker="$LOOP_MARKER" \
+      -v signaturePrefix="$SIGNATURE_PREFIX" '
+    { lines[NR] = $0 }
+    END {
+      cut = NR + 1
+      for (i = 1; i <= NR; i++) {
+        if (lines[i] == editableMarker) { cut = i; break }
+      }
+      if (cut == NR + 1) {
+        for (i = NR; i >= 1; i--) {
+          if (lines[i] == "") continue
+          if (index(lines[i], signaturePrefix) == 1) {
+            cut = i
+            if (i > 1 && (lines[i - 1] == loopMarker || lines[i - 1] == editableMarker)) cut = i - 1
+          }
+          break
+        }
+      }
+      last = cut - 1
+      while (last >= 1 && lines[last] == "") last--
+      for (i = 1; i <= last; i++) print lines[i]
+    }
+  '
+}
+
+body="$(stripExistingSignature)"
+
+case "$signatureMode" in
+  loop) marker="$LOOP_MARKER" ;;
+  editable) marker="$EDITABLE_MARKER" ;;
+  plain) marker='' ;;
+esac
+
+printf '%s\n\n' "$body"
+[ -z "$marker" ] || printf '%s\n' "$marker"
+printf '%s`%s` · [Muggle Works](%s)_\n' "$SIGNATURE_PREFIX" "$postedCommand" "$REPOSITORY_URL"

package/dist/plugin/skills/CLAUDE.md

@@ -20,6 +20,22 @@ When you feel the urge to link "up" to a caller, that is the smell — restructu
 
 `plugin/skills/skill-deps.config.json` declares support dirs grouped into their owning skill (`do/` → `muggle-do`), shared namespaces exploded to per-file nodes (`_shared`), and `knownReverseDeps` — pre-existing violations grandfathered so CI stays green. That list is debt: fix each link and delete its entry. A new reverse dependency is blocked whether or not it is on the list.
 
+## Mandatory stages
+
+A `SKILL.md` links out to the files that carry its steps, and nothing forces those links open. Read as a single page, a skill silently loses whatever its stage files required — the step is improvised instead of skipped visibly.
+
+Declare the files a skill cannot be run without in its frontmatter, paths relative to the skill directory:
+
+```yaml
+mandatoryStages:
+  - ../_shared/failure-mode-handling.md
+  - ../_shared/debug-failed-run.md
+```
+
+Invoking the skill names those files as required reading, and a Stop gate holds the turn open until each is opened (`guardrail-skill-stages.sh` / `guardrail-stage-gate.sh`, see [`../hooks/README.md`](../hooks/README.md)). The declaration is explicit rather than inferred from the prose: a gate guessing which links matter blocks on the wrong ones.
+
+The bar is "must be **read** before the skill runs", not "must be executed". A failure protocol qualifies: by the time a run fails, a skill that never read it is already improvising. What does not qualify is a file only one branch consults for its content — the gate cannot tell that the branch was not taken, so it would block work that legitimately never needed it. Aliases declare nothing; they invoke the canonical skill, which carries the declaration.
+
 ## Model tiers
 
 Each skill sets a `model:` in its `SKILL.md` frontmatter sized to its cognitive load. `model:` is a native Claude Code field — the override applies while the skill is active and reverts to the session model when it exits. Cheaper, faster models run the mechanical skills; the default (Opus) is reserved for the ones that actually reason. Cost and latency scale with the model, and these skills run often (the watcher fires every minute), so the tier is a real lever, not cosmetics.

package/dist/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/dist/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.