Fix non-zero exit on error and debounce transient mergeable=false

agentpr/watchpr already propagated command errors to a non-zero exit, but
that behaviour had no regression coverage and the root command was not
constructible outside main(). watchpr also fired a spurious conflict alert
because Gitea computes mergeability asynchronously and can briefly report
mergeable=false right after a push. The docs additionally printed the
AppRole role_id literal UUID.

- Extract newRootCmd() in both cmd/agentpr and cmd/watchpr so main() only
  runs Execute and exits non-zero on error; add tests asserting Execute
  returns an error for a bad PR ref / malformed --repo / no args.
- Debounce mergeability loss in MeaningfulChange: only alert when
  mergeable=false persists across two consecutive polls (both prev and cur
  false, still open); update the table test for one-poll-false (benign),
  false-persisting (alert), and recovered false->true (benign).
- Refer to AGENT_APPROLE_ROLE_ID by env var in README.md/AGENTS.md without
  printing the literal role_id; keep the code default and env override.

cmd/agentpr/main.go

@@ -20,6 +20,17 @@ import (
 var version = "dev"
 
 func main() {
+	// cobra prints the error itself (SilenceErrors stays off); we only need to
+	// turn any command error into a non-zero exit.
+	if err := newRootCmd().Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+// newRootCmd builds the agentpr command tree. It is separated from main so
+// tests can invoke Execute and assert the exit behaviour without spawning a
+// process.
+func newRootCmd() *cobra.Command {
 	root := &cobra.Command{
 		Use:          "agentpr",
 		Short:        "Manage Gitea PRs and comments as the unkin-agent user.",
@@ -30,10 +41,7 @@ func main() {
 	root.SetVersionTemplate("{{.Version}}\n")
 
 	root.AddCommand(newPRCmd(), newWhoamiCmd(), newVersionCmd())
-
-	if err := root.Execute(); err != nil {
-		os.Exit(1)
-	}
+	return root
 }
 
 // client mints a Gitea token via Vault and returns a ready client.

cmd/agentpr/main_test.go

@@ -0,0 +1,18 @@
+package main
+
+import (
+	"io"
+	"testing"
+)
+
+// A malformed --repo must fail the command (so main exits non-zero). ParseRepo
+// rejects it before any Vault/Gitea call, so this stays hermetic.
+func TestExecuteBadRepoErrors(t *testing.T) {
+	cmd := newRootCmd()
+	cmd.SetArgs([]string{"pr", "create", "--repo", "not-a-repo", "--base", "main", "--head", "x", "--title", "t"})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("Execute() = nil, want error for a malformed --repo")
+	}
+}

cmd/watchpr/main.go

@@ -23,6 +23,17 @@ import (
 var version = "dev"
 
 func main() {
+	// cobra prints the error itself (SilenceErrors stays off); we only need to
+	// turn any command error into a non-zero exit.
+	if err := newRootCmd().Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+// newRootCmd builds the watchpr command tree. It is separated from main so
+// tests can invoke Execute and assert the exit behaviour without spawning a
+// process.
+func newRootCmd() *cobra.Command {
 	var interval time.Duration
 	var once, jsonMode bool
 
@@ -70,10 +81,7 @@ func main() {
 		Run:          func(cmd *cobra.Command, args []string) { fmt.Println(version) },
 		SilenceUsage: true,
 	})
-
-	if err := root.Execute(); err != nil {
-		os.Exit(1)
-	}
+	return root
 }
 
 func clientFor() (*agent.GiteaClient, error) {

cmd/watchpr/main_test.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"io"
+	"testing"
+)
+
+// A bad PR reference must fail the command (so main exits non-zero) rather than
+// return nil. Parsing rejects the ref before any Vault/Gitea call, so this stays
+// hermetic.
+func TestExecuteBadRefErrors(t *testing.T) {
+	cmd := newRootCmd()
+	cmd.SetArgs([]string{"--once", "not-a-ref"})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("Execute() = nil, want error for a bad PR reference")
+	}
+}
+
+// No arguments is also an error (nothing to watch).
+func TestExecuteNoArgsErrors(t *testing.T) {
+	cmd := newRootCmd()
+	cmd.SetArgs(nil)
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("Execute() = nil, want error when no PR references are given")
+	}
+}