@muggleai/works 4.11.4 → 4.12.0

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

@@ -1,190 +1,73 @@
-# PR follow-up per-tick contract
+# Watcher Per-Tick Contract
 
-Caller-agnostic per-tick contract for the [muggle-pr-followup](SKILL.md) skill. One tick = one polling iteration scoped to one PR.
+The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews, dispatches `/muggle-do` if there are any, and exits. It does not classify, amend requirements, post replies, run cycles, or escalate.
 
-## Turn preamble
-
-```
-**PR follow-up** — polling <repo>#<pr-number>, tick #<K>.
-```
-
-Resolve `<K>` from `idle_tick_count + cycles_completed` in this PR's state slot.
-
-## When this contract may break the caller's "no questions" rule
-
-Most callers' forward pipelines never ask the user mid-cycle. This loop, however, may emit a single escalation message when a submitted review is ambiguous (see [classify](#step-6-classify-the-review) below). By the time the loop is polling, the user has walked away from the forward pipeline; forcing a guess on an ambiguous review is worse than pausing.
-
-Escalation is the **only** user-facing path. Otherwise the cycle runs silently end to end.
-
-## Inputs
-
-Read these from `.muggle-<caller>/sessions/<slug>/` (the caller's session dir):
+Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The architectural rationale lives in the brain doc `architecture/2026-05-08-muggle-do-pr-comment-loop-design.md`.
 
-- `state.md` — session metadata (for context when classifying reviews).
-- `prs.json` — list of `{repo, number, url, head_sha, state, escalated?, cycling?}`. This loop touches only the entry whose `number` matches the dispatched PR number.
-- `last_seen.json` — keyed by `"<owner>/<repo>#<n>"`. For this PR: `{reviewId, last_pushed_sha, idle_tick_count, cycles_completed, escalated_review_ids[]}`.
-- `cycle.json` — caller's declared implementation cycle (see [SKILL.md](SKILL.md#caller-supplied-implementation-cycle)).
-
-If any of these don't exist or the PR isn't in `prs.json`, the tick is a no-op — log an error to `followup.log` and exit.
-
-## Per-tick contract
-
-### Step 1: Refresh this PR's state
+## Turn preamble
 
-```bash
-gh pr view <number> --repo <repo> --json state,mergedAt,closedAt,headRefOid
 ```
-
-If `state` is `MERGED` or `CLOSED`, mark this entry terminal in `prs.json`. Update `head_sha` if it changed.
-
-### Step 2: Termination check
-
-If this PR is terminal: write a per-PR section into `result.md` (URL, final state, `cycles_completed`, count escalated, final SHA), emit final telemetry, **do not schedule another tick**. Other PRs in the session have their own loops; they terminate independently.
-
-### Step 3: Resolve the reviewer allow-list (every tick)
-
-```bash
-gh pr view <number> --repo <repo> --json reviewRequests,author
+**muggle-pr-followup tick** — polling <repo>#<pr-number>.
 ```
 
-Add requested reviewers. Add CODEOWNERS by parsing `.github/CODEOWNERS` (or `CODEOWNERS` / `docs/CODEOWNERS`) from the PR's head branch. Remove the PR author and any bot accounts (logins ending in `[bot]`, plus the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`).
+## Input
 
-### Step 4: Pull new submitted reviews
+`$ARGUMENTS = <slug> <pr-number>` (or `<pr-number>` alone — slug inferred from on-disk state per [`SKILL.md`](SKILL.md#routing)).
 
-```bash
-gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
-```
+## Inputs from disk
 
-Filter to reviews where:
+Read these from `.muggle-do/sessions/<slug>/`:
 
-- `submitted_at` is non-null (skip drafts — `PENDING` reviews are still being composed).
-- `id > last_seen.reviewId`.
-- `user.login` is in the allow-list.
-- `id` is not in `escalated_review_ids`.
-- `state` is `CHANGES_REQUESTED` or `COMMENTED`, OR `APPROVED` with at least one line comment or a non-empty body.
+- `prs.json` — see [`state-schemas.md`](state-schemas.md#prsjson). The watcher touches the single entry whose `number` matches the dispatched PR number.
+- `last_seen.json` — see [`state-schemas.md`](state-schemas.md#last_seenjson). Keyed by `"<owner>/<repo>#<n>"`.
 
-### Step 5: Pick the oldest new review
+If either file is missing or the PR is not in `prs.json`, the tick is a no-op. Log an error line in `followup.log` and exit. The watcher must not be invoked in this state — if it happens, the slot is corrupt.
 
-If no new review past the cursor: increment `idle_tick_count`, append a heartbeat line to `followup.log`, exit. Next tick fires in 1 min via `/loop`.
+## Procedure
 
-If one or more: take the oldest by `submitted_at`. Fetch its associated line comments (`gh api repos/<owner>/<repo>/pulls/<n>/comments` filtered by `pull_request_review_id`). Reset `idle_tick_count` to 0.
+### Step 1 — Refresh PR state
 
-**At most one review per tick.** If two reviews land between ticks, the second waits.
+Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). Update `prs.json[0].head_sha` and `prs.json[0].state` from the response.
 
-### Step 6: Classify the review
+### Step 2 — Termination check
 
-Apply the classify rule in [`../_shared/pr-followup-helpers.md`](../_shared/pr-followup-helpers.md). The rule applies to the **review as a unit**. Two outcomes:
+If `state` is `MERGED` or `CLOSED`:
 
-- **Actionable** → continue to Step 7.
-- **Ambiguous** → continue to Step 8.
+1. Mark the entry terminal in `prs.json`.
+2. Write `result.md` per [`state-schemas.md`](state-schemas.md#resultmd).
+3. Append a terminal line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+4. Emit a `tick` event with `terminal: true` per [`../_shared/telemetry-events/pr-followup-tick.md`](../_shared/telemetry-events/pr-followup-tick.md).
+5. Exit. **Do not schedule another tick.** The `/loop` framework stops invoking this skill once it sees no follow-up dispatch.
 
-### Step 7: Dispatch the implementation cycle
+### Step 3 — Fetch new submitted reviews
 
-When the review is actionable:
+Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). **Also exclude review ids that appear in `last_seen.escalated_review_ids`** — those have already been escalated and the watcher must not re-dispatch them.
 
-1. **Pause polling** for this PR (set `cycling: true` on this PR's entry in `prs.json`).
-2. **Amend `requirements.md`** in the session dir with a new `## Amendment — review <review_id> by <login> (<timestamp>)` section pasting the review body and each comment (with `<file>:<line>` context).
-3. **Invoke the implementation cycle** declared in the caller's `cycle.json`. Iterate the `steps[]` in order. Each step is either a markdown file to follow, a skill to invoke, or a shell command (per the `cycle.json` schema in SKILL.md). When a step fails, the cycle returns `failed: <step-name>`; the loop escalates per Step 8 with the failure as the reason.
-4. **Push** via `cycle.json`'s `pushHandler`. Set `last_seen.last_pushed_sha` to the new HEAD.
-5. **Reply** per [helpers § Reply routing](../_shared/pr-followup-helpers.md#reply-routing) and [§ Classify](../_shared/pr-followup-helpers.md#classify) (reply shape). For each line comment in the review, derive `<attribution>` from `git diff <last_pushed_sha>..HEAD -- <comment.path>` near `comment.line` ±5 (fall back to `addressed indirectly — see walkthrough` if empty). `<status>` = `ran clean` or `had <N> failures, see walkthrough`. If the review is body-only (no line comments), post the top-level fallback shape; if both body and line comments, threaded replies cover it — no top-level.
-6. **Resume polling**: clear `cycling: true`, increment `cycles_completed`, advance `last_seen.reviewId` past this review.
-7. Emit per-cycle telemetry.
+### Step 4 — If zero new reviews → idle
 
-If the cycle returns `failed: design-adjustment` (the cycle discovered the review can't be implemented without rethinking the design itself, not just the code), escalate per Step 8 with a `design-adjustment` reason — the terminal message asks the user to confirm the design intent before retrying.
+1. Increment `last_seen.idle_tick_count`.
+2. Append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+3. Emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`.
+4. Exit. The next tick fires in 1 min via `/loop`.
 
-### Step 8: Escalate
+### Step 5 — If one or more new reviews → dispatch
 
-When the review is ambiguous, or the cycle failed:
+The watcher does **not** classify. Classification, batching, replying, escalation, and cycle execution all live in `/muggle-do`. The watcher's job is to hand over the list of new review ids and exit.
 
-1. Add the review id to `last_seen.escalated_review_ids`.
-2. Append a `followup.log` entry describing the review and the reason.
-3. Pause this PR's loop by writing `escalated: true` against this PR's entry in `prs.json`.
-4. End the turn with a **single terminal message** to the user:
+1. Reset `last_seen.idle_tick_count` to 0.
+2. Dispatch `/muggle-do` with an *address-reviews* directive carrying:
+   - PR URL (from `prs.json[0].url`)
+   - Session slug (from the invocation arguments)
+   - Every new review id from Step 3, as a space-separated list
 
-```
-**PR follow-up escalation — <repo>#<number> — review <review_id>**
-
-<reviewer-login> submitted a review I can't act on coherently:
-
-> <quoted review body, or "(no body)" if empty>
-
-Comments:
-- <file>:<line> — <quoted comment body>
-
-[For ambiguous]
-Best two interpretations:
-1. <one-line interpretation A>
-2. <one-line interpretation B>
-
-[For cycle failure]
-The implementation cycle failed at <step-name>: <reason>.
-
-Reply on the review yourself, leave a follow-up comment, or tell me which way to go.
-```
-
-The user clears the escalation by replying on GitHub (next tick sees a new submitted review past the cursor) or by giving a directive in this terminal session.
-
-### Step 9: Emit tick-summary telemetry and exit
-
-Emit one tick event per `muggle-local-telemetry-skill-emit`. Exit the turn.
-
-## Reply routing
-
-- **Threaded reply per line comment** (default): `POST /repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies`. Use for every line comment in the review so each thread can be resolved in GitHub's UI.
-- **Top-level summary on a body-only review** (fallback): `gh pr comment <number> --body "..."` referencing the review id and the new SHA. Used only when the review has body content and zero line comments — GitHub has no "reply to a review body" endpoint.
-- **Never post the same reply twice** — `last_seen.reviewId` is the only re-entry guard.
-- **Never post a top-level summary alongside threaded replies** — duplication pollutes the Conversation tab.
-
-## Telemetry
-
-**Per-cycle** (one event per actionable review handled):
-
-```json
-{
-  "skill": "muggle-pr-followup",
-  "event": "cycle",
-  "caller": "<caller>",
-  "session_slug": "<slug>",
-  "repo": "<repo>",
-  "pr_number": <n>,
-  "review_id": <id>,
-  "outcome": "pushed|escalated|failed:<step>",
-  "comment_count": <count>,
-  "head_sha_before": "<sha>",
-  "head_sha_after": "<sha-or-null>"
-}
-```
-
-**Per-tick summary** (always one, even idle):
-
-```json
-{
-  "skill": "muggle-pr-followup",
-  "event": "tick",
-  "session_slug": "<slug>",
-  "repo": "<repo>",
-  "pr_number": <n>,
-  "reviews_seen": <count>,
-  "review_picked": true|false,
-  "cycle_dispatched": true|false,
-  "tick_duration_ms": <ms>
-}
-```
+   Exact phrasing belongs to `/muggle-do`'s intent-routing. A reasonable shape is:
+   ```
+   /muggle-do address reviews <id1> <id2> ... on <pr-url> slug=<slug>
+   ```
+3. Append a dispatching line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+4. Emit a `tick` event with `reviews_seen: <count>`, `dispatched_review_ids: [<id>, ...]`.
+5. Exit. **Do not schedule another tick.** `/muggle-do` will respawn the watcher at the end of its cycle.
 
 ## Output
 
-This stage produces no console output beyond:
-- The turn preamble (always).
-- An escalation terminal message (only when escalating).
-- The final `result.md` summary section for this PR (only on the terminating tick — written to disk, not printed).
-
-## Self-check before ending the turn
-
-- [ ] `last_seen.json` advanced for any review handled.
-- [ ] `prs.json` reflects current state (terminal marked; `escalated`/`cycling` flags consistent).
-- [ ] `followup.log` has at minimum a heartbeat or per-review line for this tick.
-- [ ] Telemetry events emitted (per-cycle when applicable + per-tick).
-- [ ] If pushed, `last_pushed_sha` is set and `cycles_completed` incremented.
-- [ ] If actionable, one threaded reply posted per line comment (or one top-level reply for body-only reviews) — never both, never zero.
-- [ ] If escalated, `escalated_review_ids` contains the review id.
-- [ ] If terminal, the loop is NOT continued.
+No console output beyond the turn preamble and (if Step 5 fires) the `/muggle-do` dispatch. The watcher is invisible to the reviewer.

package/plugin/skills/muggle-pr-followup/output-templates/bootstrap.md

@@ -0,0 +1,42 @@
+# Bootstrap output templates
+
+## Success summary (printed just before dispatch)
+
+```
+Bootstrapped PR follow-up for <owner>/<repo>#<n>
+  Slug:           <slug>
+  Cursor:         review #<id> (forward-only) | empty (no prior reviews)
+  Working tree:   <toplevel>
+  Dispatching:    /loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+## Aborts
+
+**Terminal PR:**
+```
+PR <owner>/<repo>#<n> is <state>; nothing to poll. Bootstrap aborted.
+```
+
+**Wrong working tree / wrong branch:**
+```
+Bootstrap needs the PR's branch checked out locally.
+Current cwd:    <toplevel-or-"not in a git repo">
+Current branch: <HEAD-or-"n/a">
+Expected:       a clone of <owner>/<repo> on branch <headRefName>.
+From that clone, run: gh pr checkout <n>
+```
+
+**Slot conflict (no `--resume`):**
+```
+Session <slug> already exists at <path>.
+To reuse it, pass --resume on this invocation.
+To start fresh, rm -rf the directory and re-run.
+```
+
+**Malformed URL:**
+```
+Could not parse <input> as a GitHub PR URL.
+Expected: https://github.com/<owner>/<repo>/pull/<number>
+```
+
+**GitHub API failure (PR not found, no auth, etc.):** repeat the underlying `gh` error verbatim. Do not paraphrase.

package/plugin/skills/muggle-pr-followup/output-templates/escalation.md

@@ -0,0 +1,32 @@
+# Escalation messages
+
+Emitted by `/muggle-do` in address-reviews mode. One per invocation, at most. Anchored here so wording stays consistent.
+
+## Ambiguous escalation
+
+```
+**Review-followup escalation — <owner>/<repo>#<n>**
+
+I can't act on <count> review(s) without your input. Listed below; reply on GitHub by submitting a new review with clearer direction, or tell me here which way to go.
+
+Review #<id> from <login>:
+> <body or "(no body)">
+
+Comments:
+- <file>:<line> — <body>
+- ...
+
+[Repeat per ambiguous review in the batch.]
+```
+
+## Design-adjustment escalation
+
+```
+**Design-adjustment needed — <owner>/<repo>#<n>**
+
+While addressing review #<id>, the cycle surfaced a conflict with the current design:
+
+  <one-paragraph description of the conflict>
+
+This is beyond a routine code change. Confirm the design intent (reply here, or update the requirements doc) before I retry.
+```

package/plugin/skills/muggle-pr-followup/output-templates/help.md

@@ -0,0 +1,17 @@
+# Help output
+
+For `/muggle:muggle-pr-followup` with no args, or with `help` / `?`:
+
+```
+muggle-pr-followup — watcher loop for PR review follow-ups
+
+Active loops:
+  <slug> → <owner>/<repo>#<n> (cursor @ review #<id>, <N> cycles)
+  ...
+  (or "no active loops")
+
+Usage:
+  /muggle:muggle-pr-followup <pr-url>            → bootstrap a new loop
+  /muggle:muggle-pr-followup <slug> <pr-number>  → run one tick (called by /loop)
+  /muggle:muggle-pr-followup <pr-number>         → run one tick (slug inferred from on-disk state)
+```

package/plugin/skills/muggle-pr-followup/output-templates/inline-reply.md

@@ -0,0 +1,17 @@
+# Per-comment inline reply
+
+Posted via `gh api .../comments/<comment-id>/replies` per cycle, one per line comment.
+
+```
+Addressed in <short-sha>: <one-line summary of the change made for THIS comment>.
+```
+
+`<short-sha>` is the first 7 chars of the new SHA. The body must contain that substring — the resolve-reminder stage greps for it to classify threads as addressed-by-loop.
+
+## Top-level fallback (review-body-only)
+
+When an actionable review has a non-empty body but zero line comments, GitHub has no `/replies` endpoint for the body. Post a top-level PR comment instead, at most once per such review:
+
+```
+Re: review #<review_id> — addressed in <short-sha>: <one-line summary>.
+```

package/plugin/skills/muggle-pr-followup/output-templates/resolve-reminder.md

@@ -0,0 +1,12 @@
+# Resolve-reminder top-level PR comment
+
+Posted via `gh pr comment` after the resolve-reminder stage scans threads. Only when at least one addressed-by-loop thread exists.
+
+```
+I addressed these threads in <short-sha> — mark them resolved when satisfied:
+- #<thread-id-1>
+- #<thread-id-2>
+- ...
+```
+
+If `addressed_by_loop == 0`, no comment is posted (silent).

package/plugin/skills/muggle-pr-followup/output-templates/watcher-log.md

@@ -0,0 +1,21 @@
+# Watcher tick log lines
+
+The watcher does **not** print to the user during normal operation. It only appends to `followup.log`. All user-facing escalations come from `/muggle-do`.
+
+## Idle tick
+
+```
+<ISO-8601> tick pr=<n> reviews_seen=0 idle
+```
+
+## Dispatching tick
+
+```
+<ISO-8601> tick pr=<n> reviews_seen=<count> dispatched=<id1>,<id2>,...
+```
+
+## Terminal tick
+
+```
+<ISO-8601> tick pr=<n> terminal=<merged|closed> result.md written
+```

package/plugin/skills/muggle-pr-followup/output-templates.md

@@ -0,0 +1,14 @@
+# Output templates
+
+All user-facing message text used by the watcher, bootstrap, and `/muggle-do` in address-reviews mode. Each template group is its own file — load only what the current step emits.
+
+## Index
+
+| Group | Use case |
+| :---- | :------- |
+| [`bootstrap`](output-templates/bootstrap.md) | Bootstrap success summary + all bootstrap aborts. |
+| [`watcher-log`](output-templates/watcher-log.md) | The three `followup.log` line shapes (idle, dispatching, terminal). |
+| [`escalation`](output-templates/escalation.md) | `/muggle-do` terminal escalation messages (ambiguous, design-adjustment). |
+| [`inline-reply`](output-templates/inline-reply.md) | Per-comment inline reply + top-level fallback for body-only reviews. |
+| [`resolve-reminder`](output-templates/resolve-reminder.md) | Top-level PR comment for the resolve-reminder stage. |
+| [`help`](output-templates/help.md) | Skill help output (no args / `help` / `?`). |

package/plugin/skills/muggle-pr-followup/state-schemas.md

@@ -0,0 +1,104 @@
+# Session State Schemas
+
+Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `.muggle-do/sessions/<slug>/` (the caller's session dir; `muggle-do` is the current and only caller).
+
+All files are atomic writes — the caller rewrites the whole file each time, never mutates in place. Use a temp file + rename if the platform supports it.
+
+## `prs.json`
+
+A list of one entry. (Historical: the file is an array for forward-compat with the original session-wide model. Today, each PR has its own session slot, so the array always has exactly one entry.)
+
+```json
+[
+  {
+    "repo": "<owner>/<repo>",
+    "number": <int>,
+    "url": "https://github.com/<owner>/<repo>/pull/<number>",
+    "head_sha": "<40-char-hex-sha>",
+    "state": "open" | "merged" | "closed"
+  }
+]
+```
+
+- `state` is the **observed** state from the last `gh pr view`. The watcher refreshes it each tick.
+- Terminal states (`merged`, `closed`) are sticky — once set, the watcher writes `result.md` and exits without rescheduling.
+
+## `last_seen.json`
+
+Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
+
+```json
+{
+  "<owner>/<repo>#<n>": {
+    "reviewId": <int>,
+    "last_pushed_sha": "<sha-or-null>",
+    "idle_tick_count": <int>,
+    "cycles_completed": <int>,
+    "escalated_review_ids": [<int>, ...],
+    "pushed_shas": ["<sha>", ...]
+  }
+}
+```
+
+- `reviewId`: the cursor. The watcher fetches reviews with `id > reviewId`. Bootstrap pins this to the highest existing submitted review id (or `0` if none).
+- `last_pushed_sha`: most recent SHA `/muggle-do` pushed in this PR's life; `null` until the first push.
+- `idle_tick_count`: incremented each tick that sees zero new reviews. Reset to 0 on any tick that dispatches `/muggle-do`. Diagnostic only — does not gate behavior.
+- `cycles_completed`: incremented each time `/muggle-do` completes an address-reviews invocation (regardless of actionable/ambiguous/mixed).
+- `escalated_review_ids`: review ids classified as ambiguous by `/muggle-do`. The watcher excludes these from future review fetches so the same ambiguous review is never re-dispatched.
+- `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
+
+## `state.md`
+
+Free-form markdown. No required schema beyond a few well-known fields the caller-agnostic code reads:
+
+```markdown
+# Session — <slug>
+
+**PR:** <url>
+**Slug:** <slug>
+**Loop user:** <github-login>          ← cached from `gh api user`
+**Created:** <ISO-8601>
+**Bootstrapped from URL:** <yes | no>
+
+...free-form notes added by /muggle-do and bootstrap...
+```
+
+The watcher does **not** read or write `state.md`. Only bootstrap, `/muggle-do`, and the caller's stages touch it.
+
+## `followup.log`
+
+Append-only line-per-tick log. One line per watcher tick, plus one line per `/muggle-do` invocation. Format is loose, but each line starts with an ISO-8601 timestamp:
+
+```
+2026-05-20T12:34:56Z tick pr=154 reviews_seen=0 idle
+2026-05-20T12:35:56Z tick pr=154 reviews_seen=1 dispatched=4295962800
+2026-05-20T12:36:14Z muggle-do cycle review_ids=[4295962800] outcome=pushed head_sha=abc1234
+```
+
+Used for forensics only — never read back by skills.
+
+## `result.md`
+
+Written exactly once when the PR's watcher exits terminally (PR merged or closed). Free-form markdown summarizing the PR's life under this loop:
+
+```markdown
+# Result — <slug>
+
+**PR:** <url>
+**Final state:** merged | closed
+**Cycles completed:** <int>
+**Pushed SHAs:** <comma-separated list>
+**Escalated review ids:** <comma-separated list or "none">
+
+## Timeline
+
+- <ISO-8601> bootstrap (cursor pinned at <reviewId>)
+- <ISO-8601> review <id> from <login> — actionable, pushed <sha>
+- <ISO-8601> review <id> from <login> — ambiguous, escalated
+- ...
+- <ISO-8601> PR <merged|closed> — watcher terminal
+```
+
+## Not in the slot
+
+`cycle.json` and `requirements.md` are not seeded or read. `/muggle-do` reads reviews off GitHub each invocation.

package/plugin/skills/muggle-test-regenerate-missing/SKILL.md

@@ -180,15 +180,15 @@ Bulk regen does not run replays, so the section B (replay) router does not apply
 
 ### Step 8 — Open the Dashboard
 
-Open the Muggle AI dashboard so the user can watch progress visually:
+Open the Muggle AI dashboard so the user can watch progress visually. Point them at the **scripts** page (where DRAFT → GENERATING → ACTIVE transitions are visible), not `/runs` (which is for replay batches and shows nothing for a regen):
 
 ```bash
-open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
+open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts"
 ```
 
 Tell them:
 
-> "I've opened the project's runs page. Generation jobs typically take a few minutes each — they'll appear here as they progress. Your test cases will move into `ACTIVE` status as scripts complete."
+> "I've opened the project's scripts page. Generation jobs typically take a few minutes each — your test cases will move from `DRAFT` through `GENERATING` to `ACTIVE` as scripts complete."
 
 ### Step 9 (optional) — Poll Status
 

package/scripts/postinstall.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* global AbortController */
 /**
  * Postinstall script for @muggleai/works.
  * Downloads the Electron app binary for local testing.
@@ -30,6 +31,8 @@ const VERSION_DIRECTORY_NAME_PATTERN = /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/;
 const INSTALL_METADATA_FILE_NAME = ".install-metadata.json";
 const INSTALL_MANIFEST_FILE_NAME = "install-manifest.json";
 const LOG_FILE_NAME = "postinstall.log";
+const FETCH_TIMEOUT_MS = 90_000;
+const STREAM_TIMEOUT_MS = 5 * 60_000;
 const VERSION_OVERRIDE_FILE_NAME = "electron-app-version-override.json";
 const CURSOR_SKILLS_DIRECTORY_NAME = ".cursor";
 const CURSOR_SKILLS_SUBDIRECTORY_NAME = "skills";
@@ -625,9 +628,22 @@ async function downloadElectronApp() {
         // Create directories
         mkdirSync(versionDir, { recursive: true });
 
-        // Download using fetch
+        // Download using fetch. Both fetch and pipeline get hard timeouts so a
+        // hung CDN/proxy can never pin this process — see issue #167.
         log("Fetching...");
-        const response = await fetch(downloadUrl);
+        const fetchController = new AbortController();
+        const fetchTimer = setTimeout(() => fetchController.abort(), FETCH_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(downloadUrl, { signal: fetchController.signal });
+        } catch (error) {
+            if (error && error.name === "AbortError") {
+                throw new Error(`Fetch timed out after ${FETCH_TIMEOUT_MS}ms — ${downloadUrl}`, { cause: error });
+            }
+            throw error;
+        } finally {
+            clearTimeout(fetchTimer);
+        }
         if (!response.ok) {
             const errorBody = await response.text().catch(() => "");
             throw new Error(
@@ -642,7 +658,18 @@ async function downloadElectronApp() {
 
         const tempFile = join(versionDir, binaryName);
         const fileStream = createWriteStream(tempFile);
-        await pipeline(response.body, fileStream);
+        const streamController = new AbortController();
+        const streamTimer = setTimeout(() => streamController.abort(), STREAM_TIMEOUT_MS);
+        try {
+            await pipeline(response.body, fileStream, { signal: streamController.signal });
+        } catch (error) {
+            if (error && error.name === "AbortError") {
+                throw new Error(`Download stream stalled — aborted after ${STREAM_TIMEOUT_MS}ms`, { cause: error });
+            }
+            throw error;
+        } finally {
+            clearTimeout(streamTimer);
+        }
 
         log("Download complete, verifying checksum...");
 
@@ -895,10 +922,14 @@ function syncClaudePluginCache() {
     }
 }
 
-// Run postinstall
+// Run postinstall. The explicit `process.exit` guarantees the script doesn't
+// linger when something below (a hung socket, an EPERM rmSync retry on
+// Windows) keeps the event loop alive — see issue #167.
 initLogFile();
 removeVersionOverrideFile();
 syncCursorSkills();
 syncClaudePluginCache();
 upsertCursorMcpConfig();
-downloadElectronApp().catch(logError);
+downloadElectronApp()
+    .catch(logError)
+    .finally(() => process.exit(0));