fix(amp): replace the impossible phx-watch-pr install command (#137)

README and docs/amp.md told users to install the watcher with `amp plugins
add` against a raw.githubusercontent.com URL. Amp rejects that outright:

  Error: For now, only https://ampcode.com/@amp/plugins/*.ts and
  https://ampcode.com/@amp/plugins/*.ts URLs are allowed.

Verified on Amp 0.0.1787045288. Nothing is written, so the documented path
to the watcher never worked for anyone.

docs/amp.md already contradicted itself about this: 390 lines below the
install block it states that Amp "restricts `amp plugins add` ... to
Amp-hosted plugins" and hands out an atomic curl for elixir-phoenix.ts. The
install instruction was simply the wrong half of the contradiction. Both
call sites now use that same curl + mv pattern against the standalone
repository's stable branch, verified to fetch bytes identical to the
canonical target. The update section loops over both plugins rather than
only the workflow one.

Also raises the phx-watch-pr harness subprocess timeout from 60s to 240s.
The harness drives a fake clock with real 80ms flushes -- advance() runs up
to 21 per call across 23 calls -- so it spends ~59s waiting for ~3s of CPU.
Consecutive local runs took 58.9s, 60.4s, and 73.9s, so a required check
was passing or failing on runner load alone. The harness is unchanged;
shortening the flush would swap a timeout flake for a race.

Fixes a paragraph-join in README introduced when the watch-pr block was
merged forward in #132.

Author: oliver-kriska

CHANGELOG.md

@@ -99,6 +99,27 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **The `phx-watch-pr` harness test was one second from red** — it ran with a
+  60-second subprocess timeout and takes ~59 seconds of wall time for ~3 seconds
+  of CPU: the harness drives a fake clock with real 80ms flushes, and `advance()`
+  performs up to 21 of them across 23 calls. Observed locally at 58.9s, 60.4s,
+  and 73.9s on consecutive runs, so it passes or fails on runner load alone —
+  and it is a required check, meaning it would have started blocking unrelated
+  PRs. Raised to 240s; the harness itself is unchanged, since shortening the
+  flush would trade a timeout flake for a race.
+
+- **The `phx-watch-pr` install command could never have worked** — README and
+  `docs/amp.md` told users to run `amp plugins add` against a
+  `raw.githubusercontent.com` URL. Amp `0.0.1787045288` rejects that with
+  `For now, only https://ampcode.com/@amp/plugins/*.ts ... URLs are allowed` and
+  writes nothing. The same `docs/amp.md` already said, 390 lines further down,
+  that "Amp currently restricts `amp plugins add` ... to Amp-hosted plugins" —
+  the file contradicted itself, and the install instruction was the wrong half.
+  Both call sites now use the atomic `curl` + `mv` pattern already documented
+  for `elixir-phoenix.ts`, pointing at the standalone repository's `stable`
+  branch. The update section covers both plugins instead of only the workflow
+  one.
+
 - **Upgrading from v2.x no longer lands users in a dead install** (reported by
   @barquesurlocean, #135) — v3.0.0 renamed the plugin manifest to `phx` (which
   is what makes `/phx:*` correct; pre-v3 versions namespaced their commands as

README.md

@@ -306,13 +306,17 @@ hosted artifacts are managed through Amp's Personal Settings or personal Git
 repositories and work across machines and orbs. See the complete [Amp guide](docs/amp.md)
 for hosted publication, source precedence, wrapper limits, updates, fallback
 installation, specialists, safety boundaries, and verification.
+
 `phx-watch-pr` additionally needs the separate `phx-watch-pr.ts` plugin.
 Install it into the project where the worker Orb opens and watches PRs:
 
 ```bash
-amp plugins add \
-  https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/main/targets/amp/plugins/phx-watch-pr.ts \
-  --target workspace
+mkdir -p .amp/plugins
+plugin=".amp/plugins/phx-watch-pr.ts"
+temporary="$(mktemp "${plugin}.XXXXXX")"
+curl --fail --silent --show-error --location \
+  https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/phx-watch-pr.ts \
+  --output "$temporary" && mv "$temporary" "$plugin"
 ```
 
 It holds a bounded Orb keep-alive lease, filters deployment-like checks out of

docs/amp.md

@@ -112,9 +112,12 @@ generated Amp plugin because only the Plugin API can hold an Orb keep-alive
 lease and wake the same thread after inactivity:
 
 ```bash
-amp plugins add \
-  https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/main/targets/amp/plugins/phx-watch-pr.ts \
-  --target workspace
+mkdir -p .amp/plugins
+plugin=".amp/plugins/phx-watch-pr.ts"
+temporary="$(mktemp "${plugin}.XXXXXX")"
+curl --fail --silent --show-error --location \
+  https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/phx-watch-pr.ts \
+  --output "$temporary" && mv "$temporary" "$plugin"
 ```
 
 Start a fresh Amp process or run `plugins: reload`. Plugins execute code; audit
@@ -501,18 +504,22 @@ normal update path, but removal followed by installation is the exact-sync path
 when a release deletes or renames a skill.
 
 Amp currently restricts `amp plugins add` and directive-based auto-updates to
-Amp-hosted plugins. Update this GitHub-hosted plugin by downloading the current
-validated file again, or remove it with Amp:
+Amp-hosted plugins; it rejects any other URL outright. Update these
+GitHub-hosted plugins by downloading the current validated file again, or remove
+them with Amp:
 
 ```bash
-# Update the workspace plugin atomically
-plugin=".amp/plugins/elixir-phoenix.ts"
-temporary="$(mktemp "${plugin}.XXXXXX")"
-curl --fail --silent --show-error --location \
-  https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/elixir-phoenix.ts \
-  --output "$temporary" && mv "$temporary" "$plugin"
-
-# Remove the workspace-scoped installation
+# Update a workspace plugin atomically
+for name in elixir-phoenix phx-watch-pr; do
+  plugin=".amp/plugins/${name}.ts"
+  [ -f "$plugin" ] || continue
+  temporary="$(mktemp "${plugin}.XXXXXX")"
+  curl --fail --silent --show-error --location \
+    "https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/${name}.ts" \
+    --output "$temporary" && mv "$temporary" "$plugin"
+done
+
+# Remove a workspace-scoped installation
 amp plugins remove elixir-phoenix.ts --target workspace
 ```
 

scripts/tests/test_amp.py

@@ -443,7 +443,10 @@ def test_native_watch_plugin_lifecycle_harness(tmp_path) -> None:
         cwd=Path(__file__).parents[2],
         text=True,
         capture_output=True,
-        timeout=60,
+        # The harness drives a fake clock with real 80ms flushes: advance() runs
+        # up to 21 of them and is called 23 times, so the run is ~59s of waiting
+        # against ~3s of CPU. A 60s limit left under a second of margin.
+        timeout=240,
     )
 
     assert result.returncode == 0, result.stderr or result.stdout