From dc791e0c76b6d7da01e42e589446fe54bb50d1a2 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 14:15:24 -0500 Subject: [PATCH 1/7] =?UTF-8?q?=F0=9F=90=9B=20fix:=20let=20the=20agent=20t?= =?UTF-8?q?hat=20opened=20a=20PR=20reply=20on=20its=20review=20threads?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The review-feedback sweep kicked the opening agent, but the proxy rule table had no rule for pulls/comments/{id}/replies, pulls/{n}/comments or comment DELETE, so all three fell through to deny-by-default while issue comments passed. Allow the reply routes only on a PR the hive's own agent opened (audit trail agent_pr_created) and only for that agent; allow DELETE only of the hive's own comment within 15 minutes. Keep a refused reply for the sweep's needs-human note, and tell the agent in the brief to use the replies endpoint, never post probe comments, and stop on a refusal. Fixes #19096 Signed-off-by: Andy Anderson --- .../fixed-19096-review-thread-replies.md | 1 + src/cmd/hive/main.go | 11 + src/cmd/hive/review_feedback_wire.go | 132 +++++- src/cmd/hive/review_feedback_wire_test.go | 92 ++++ src/crux/proxy/github_proxy.go | 3 + src/crux/proxy/github_proxy_mitm.go | 10 + src/crux/proxy/reference_repos.go | 9 +- src/crux/proxy/review_thread.go | 361 ++++++++++++++++ src/crux/proxy/review_thread_test.go | 405 ++++++++++++++++++ src/crux/proxy/rules.go | 10 + src/docs/github-write-surface.md | 29 ++ .../labels-and-control-signals/reference.md | 2 +- src/pkg/reviewfeedback/reviewfeedback.go | 103 ++++- src/pkg/reviewfeedback/reviewfeedback_test.go | 82 +++- 14 files changed, 1226 insertions(+), 24 deletions(-) create mode 100644 changelog.d/fixed-19096-review-thread-replies.md create mode 100644 src/crux/proxy/review_thread.go create mode 100644 src/crux/proxy/review_thread_test.go diff --git a/changelog.d/fixed-19096-review-thread-replies.md b/changelog.d/fixed-19096-review-thread-replies.md new file mode 100644 index 0000000000..a2a70ecd4e --- /dev/null +++ b/changelog.d/fixed-19096-review-thread-replies.md @@ -0,0 +1 @@ +- Let the agent that opened a PR reply inside its review threads (`pulls/comments/{id}/replies`, `pulls/{n}/comments`) and retract the hive's own comment within 15 minutes; every other PR, agent and comment stays refused, the review-feedback brief forbids probe comments, and a refused reply is posted in the sweep's needs-human note for a person (#19096). diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 37029483f7..271cc1dffe 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -4291,6 +4291,17 @@ func (b *boot) bootProxyWith(deps bootProxyDeps) { // unconditionally: with HIVE_PROXY_INJECT_GH_AUTH unset (the default) // the proxy never consults the source and the registry stays empty. b.githubProxy.SetAgentTokenSource(github.AgentProxyToken) + // Review-thread replies on the hive's own PRs (#19096): the proxy lets + // the agent that opened a PR (audit trail agent_pr_created) reply in + // its review threads, lets the hive retract its own comment for a + // short window, and keeps any refused reply for the review-feedback + // sweep's needs-human note. The closures read b.cfg and the live client per + // call because both are replaced on reload and key rotation. + b.githubProxy.SetReviewThreadGuard(newReviewThreadGuard( + func() string { return b.cfg.Project.Org }, + func() string { return b.currentGitHubClient().AppBotLogin() }, + b.logger, + )) // project.reference_repos (#18015): study-only repos outside the // project, with a rare per-entry issues/prs opt-in served by a // credential verified here (boot refuses otherwise). diff --git a/src/cmd/hive/review_feedback_wire.go b/src/cmd/hive/review_feedback_wire.go index 769ce48340..5638e38983 100644 --- a/src/cmd/hive/review_feedback_wire.go +++ b/src/cmd/hive/review_feedback_wire.go @@ -6,9 +6,11 @@ import ( "sort" "strconv" "strings" + "sync" "time" "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/proxy" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/github" "github.com/hivecommons/hive/pkg/reviewfeedback" @@ -36,10 +38,97 @@ const ( var ( reviewFeedbackLastRun time.Time reviewFeedbackCursor int + // reviewFeedbackStore is shared by the sweep and the proxy's refused-reply + // hook (#19096), which run on different goroutines; open it through + // openReviewFeedbackStore. reviewFeedbackStore *reviewfeedback.Store reviewRuleStore *reviewrules.Store + reviewFeedbackStoreMu sync.Mutex ) +// openReviewFeedbackStore opens the sweep's state once and returns it. +func openReviewFeedbackStore(logger *slog.Logger) *reviewfeedback.Store { + reviewFeedbackStoreMu.Lock() + defer reviewFeedbackStoreMu.Unlock() + if reviewFeedbackStore == nil { + st, err := reviewfeedback.Open(reviewfeedback.Dir()) + if err != nil { + logger.Warn("review feedback: state unreadable or not writable; handled ids kept in memory only", "dir", reviewfeedback.Dir(), "error", err) + } + reviewFeedbackStore = st + } + return reviewFeedbackStore +} + +// reviewThreadOwnersTTL bounds how long the audit-trail PR ownership map the +// proxy's review-thread gate reads is reused before it is read again. +const reviewThreadOwnersTTL = time.Minute + +// reviewThreadOwners caches auditPRAgents for the proxy gate, which is asked +// per request: reading the audit log on every reply would be wasteful, and a +// PR opened a minute ago is not yet being reviewed. +type reviewThreadOwners struct { + mu sync.Mutex + at time.Time + owners map[string]string + org func() string + load func(org string, since time.Time) map[string]string + now func() time.Time +} + +// owner returns the agent that opened repo#number, from the same audit-trail +// source the sweep uses (agent_pr_created within auditPRAttributionWindow). +func (o *reviewThreadOwners) owner(repo string, number int) (string, bool) { + o.mu.Lock() + defer o.mu.Unlock() + now := o.now() + if o.owners == nil || now.Sub(o.at) >= reviewThreadOwnersTTL { + o.owners = o.load(o.org(), now.Add(-auditPRAttributionWindow)) + o.at = now + } + key := reviewfeedback.Key(repo, number) + if agent, ok := o.owners[key]; ok && agent != "" { + return agent, true + } + for k, agent := range o.owners { + if agent != "" && strings.EqualFold(k, key) { + return agent, true + } + } + return "", false +} + +// newReviewThreadGuard builds the proxy's review-thread gate seams (#19096): +// PR ownership from the audit trail, the hive's App bot login, and the hook +// that keeps a refused reply for the sweep's needs-human note. +func newReviewThreadGuard(org func() string, botLogin func() string, logger *slog.Logger) proxy.ReviewThreadGuard { + owners := &reviewThreadOwners{ + org: org, + load: func(org string, since time.Time) map[string]string { + return auditPRAgents(org, since, "") + }, + now: time.Now, + } + return proxy.ReviewThreadGuard{ + OwnPR: owners.owner, + HiveLogins: func() []string { + if l := strings.TrimSpace(botLogin()); l != "" { + return []string{l} + } + return nil + }, + OnRefused: func(r proxy.ReviewWriteRefusal) { + key := reviewfeedback.Key(r.Repo, r.Number) + err := openReviewFeedbackStore(logger).RecordBlockedReply(key, reviewfeedback.ReplyDraft{InReplyTo: r.InReplyTo, Body: r.Body, Agent: r.Agent, At: r.At}) + if err != nil { + logger.Warn("review feedback: refused reply not kept for the needs-human note", "repo", r.Repo, "pr", r.Number, "agent", r.Agent, "error", err) + return + } + logger.Info("review feedback: reply refused by the proxy, kept for a person", "repo", r.Repo, "pr", r.Number, "agent", r.Agent, "in_reply_to", r.InReplyTo) + }, + } +} + // reviewFeedbackSource is the GitHub surface the sweep needs. type reviewFeedbackSource interface { FetchPRFeedback(ctx context.Context, repo string, number int) (github.PRFeedback, error) @@ -120,13 +209,21 @@ func (s reviewFeedbackSweep) run(ctx context.Context, parse func(key string) (re s.Logger.Warn("review feedback: fetch failed, PR skipped this pass", "repo", repo, "pr", number, "error", err) continue } - if s.Rules != nil && fb.Open() { + if !fb.Open() { + continue + } + if s.Rules != nil { s.applyRuleReplies(repo, number, fb.HiveReplies) s.postRuleNotices(ctx, repo, number) s.checkRuleReply(ctx, key, repo, number, fb.AgentReplies, &res) s.captureRules(ctx, repo, number, redPRFixOwner(s.Owners[key]), fb.RuleCandidates, &res) } - if !fb.Open() || len(fb.Items) == 0 { + // Replies the agent drafted but the proxy refused (#19096): hand them + // to a person instead of letting them vanish. + if drafts := s.Store.BlockedDraftsDue(key, s.Now, s.Limits.Window); len(drafts) > 0 { + s.needsHuman(ctx, key, repo, number, "the hive's proxy refused the reply, so it was not posted", nil, drafts, &res) + } + if len(fb.Items) == 0 { continue } d := s.Store.Plan(key, fb.Items, s.Now, s.Limits) @@ -136,11 +233,11 @@ func (s reviewFeedbackSweep) run(ctx context.Context, parse func(key string) (re s.Logger.Debug("review feedback: burst still arriving, waiting to coalesce", "repo", repo, "pr", number, "comments", len(d.Items)) case reviewfeedback.VerdictCapReached: res.CapReached++ - s.needsHuman(ctx, key, repo, number, "it has been routed to its agent "+strconv.Itoa(s.Limits.WindowCap)+" times in "+s.Limits.Window.String()+"; further feedback is waiting, and a new comment from a person resets this", d.Items, &res) + s.needsHuman(ctx, key, repo, number, "it has been routed to its agent "+strconv.Itoa(s.Limits.WindowCap)+" times in "+s.Limits.Window.String()+"; further feedback is waiting, and a new comment from a person resets this", d.Items, nil, &res) case reviewfeedback.VerdictKick: recorded := s.recordedRules(repo, number, d.Items) if route.Agent == "" { - s.needsHuman(ctx, key, repo, number, route.Reason, d.Items, &res) + s.needsHuman(ctx, key, repo, number, route.Reason, d.Items, nil, &res) continue } brief := reviewfeedback.BuildBriefWithRules(repo, number, fb.HeadRef, s.WritingGuide, d.Items, recorded) @@ -174,16 +271,23 @@ func (s reviewFeedbackSweep) run(ctx context.Context, parse func(key string) (re return res } -func (s reviewFeedbackSweep) needsHuman(ctx context.Context, key, repo string, number int, reason string, items []github.FeedbackItem, res *reviewFeedbackResult) { - if s.Store.NeedsHumanNoted(key) { +// needsHuman posts the needs-human note: once per PR when feedback cannot be +// routed, or with drafts set, the replies the agent drafted but could not +// post (#19096), at most once per Limits.Window (BlockedDraftsDue). +func (s reviewFeedbackSweep) needsHuman(ctx context.Context, key, repo string, number int, reason string, items []github.FeedbackItem, drafts []reviewfeedback.ReplyDraft, res *reviewFeedbackResult) { + if len(drafts) == 0 && s.Store.NeedsHumanNoted(key) { return } - s.Logger.Warn("review feedback: cannot route to an agent, asking a person", "repo", repo, "pr", number, "reason", reason, "comments", len(items)) - if err := s.Source.CreateIssueComment(ctx, repo, number, reviewfeedback.NeedsHumanNote(reason, items)); err != nil { // writeback:solicited a person's review feedback on this hive-authored PR + s.Logger.Warn("review feedback: cannot route to an agent, asking a person", "repo", repo, "pr", number, "reason", reason, "comments", len(items), "drafted_replies", len(drafts)) + if err := s.Source.CreateIssueComment(ctx, repo, number, reviewfeedback.NeedsHumanNote(reason, items, drafts)); err != nil { // writeback:solicited a person's review feedback on this hive-authored PR s.Logger.Warn("review feedback: needs-human note not posted", "repo", repo, "pr", number, "error", err) return } - if _, err := s.Store.MarkNeedsHuman(key, s.Now); err != nil { + if len(drafts) > 0 { + if err := s.Store.MarkBlockedNoted(key, drafts, s.Now); err != nil { + s.Logger.Warn("review feedback: could not persist drafted-replies hand-off", "repo", repo, "pr", number, "error", err) + } + } else if _, err := s.Store.MarkNeedsHuman(key, s.Now); err != nil { s.Logger.Warn("review feedback: could not persist needs-human flag", "repo", repo, "pr", number, "error", err) } res.NeedsHuman++ @@ -379,13 +483,7 @@ func sweepReviewFeedback(ctx context.Context, cfg *config.Config, client *github return } reviewFeedbackLastRun = now - if reviewFeedbackStore == nil { - st, err := reviewfeedback.Open(reviewfeedback.Dir()) - if err != nil { - logger.Warn("review feedback: state unreadable or not writable; handled ids kept in memory only", "dir", reviewfeedback.Dir(), "error", err) - } - reviewFeedbackStore = st - } + store := openReviewFeedbackStore(logger) if reviewRuleStore == nil && reviewrules.Enabled() { rs, err := reviewrules.Open(reviewrules.Dir(), reviewrules.VaultDir(), reviewrules.ConfigFromEnv()) if err != nil { @@ -401,7 +499,7 @@ func sweepReviewFeedback(ctx context.Context, cfg *config.Config, client *github available := agentAvailability(cfg, agentMgr) sweep := reviewFeedbackSweep{ Source: client, - Store: reviewFeedbackStore, + Store: store, Owners: auditPRAgents(cfg.Project.Org, now.Add(-auditPRAttributionWindow), ""), Kicker: agentKicker{mgr: agentMgr}, WritingGuide: cfg.Project.WritingGuideSection(), diff --git a/src/cmd/hive/review_feedback_wire_test.go b/src/cmd/hive/review_feedback_wire_test.go index 6d15dcdbd5..c9a6f69cf9 100644 --- a/src/cmd/hive/review_feedback_wire_test.go +++ b/src/cmd/hive/review_feedback_wire_test.go @@ -7,6 +7,7 @@ import ( "testing" "time" + "github.com/hivecommons/hive/crux/proxy" "github.com/hivecommons/hive/pkg/github" "github.com/hivecommons/hive/pkg/reviewfeedback" ) @@ -223,3 +224,94 @@ func TestParseReviewFeedbackKey(t *testing.T) { } } } + +// A reply the proxy refused (#19096) is handed to a person once with the +// drafted text, even when no new feedback is waiting, and a second pass inside +// the window posts nothing more. +func TestReviewFeedbackSweep_RefusedReplyPostsDraftsOnce(t *testing.T) { + fb := openDraftFeedback() + fb.Items = nil + src := &fakeFeedbackSource{byKey: map[string]github.PRFeedback{feedbackTestKey: fb}} + now := time.Now() + s := feedbackSweepFor(t, src, &recordingKicker{}, routeTo("quality"), now) + if err := s.Store.RecordBlockedReply(feedbackTestKey, reviewfeedback.ReplyDraft{InReplyTo: "4616203214", Body: "Verified the scorecard; fixed in abc123.", Agent: "quality", At: now}); err != nil { + t.Fatal(err) + } + res := s.run(context.Background(), parseReviewFeedbackKey) + if res.NeedsHuman != 1 || len(src.comments) != 1 { + t.Fatalf("needs_human=%d comments=%d, want one note", res.NeedsHuman, len(src.comments)) + } + for _, want := range []string{github.FeedbackNeedsHumanMarker, "could not post its replies", "4616203214", "fixed in abc123"} { + if !strings.Contains(src.comments[0], want) { + t.Errorf("note missing %q:\n%s", want, src.comments[0]) + } + } + s.Now = now.Add(10 * time.Minute) + if res := s.run(context.Background(), parseReviewFeedbackKey); res.NeedsHuman != 0 || len(src.comments) != 1 { + t.Fatalf("second pass must not post again: needs_human=%d comments=%d", res.NeedsHuman, len(src.comments)) + } +} + +func TestReviewThreadOwners_AuditOwnershipCachedAndCaseInsensitive(t *testing.T) { + loads := 0 + now := time.Now() + o := &reviewThreadOwners{ + org: func() string { return "cncf" }, + load: func(org string, _ time.Time) map[string]string { + loads++ + return map[string]string{"cncf/techdocs#424": "quality"} + }, + now: func() time.Time { return now }, + } + cases := []struct { + name string + repo string + number int + wantAgent string + wantOK bool + }{ + {"hive-authored PR", "cncf/techdocs", 424, "quality", true}, + {"case-insensitive repo", "CNCF/TechDocs", 424, "quality", true}, + {"other PR", "cncf/techdocs", 425, "", false}, + {"other repo", "cncf/toc", 424, "", false}, + } + for _, tc := range cases { + agent, ok := o.owner(tc.repo, tc.number) + if agent != tc.wantAgent || ok != tc.wantOK { + t.Errorf("%s: owner=%q ok=%v, want %q %v", tc.name, agent, ok, tc.wantAgent, tc.wantOK) + } + } + if loads != 1 { + t.Fatalf("audit read %d times inside the TTL, want 1", loads) + } + now = now.Add(reviewThreadOwnersTTL) + o.owner("cncf/techdocs", 424) + if loads != 2 { + t.Fatalf("audit must be re-read after the TTL, loads=%d", loads) + } +} + +func TestNewReviewThreadGuard_LoginsAndRefusedReplyKept(t *testing.T) { + t.Setenv(reviewfeedback.DirEnvVar, t.TempDir()) + reviewFeedbackStoreMu.Lock() + prev := reviewFeedbackStore + reviewFeedbackStore = nil + reviewFeedbackStoreMu.Unlock() + t.Cleanup(func() { + reviewFeedbackStoreMu.Lock() + reviewFeedbackStore = prev + reviewFeedbackStoreMu.Unlock() + }) + g := newReviewThreadGuard(func() string { return "cncf" }, func() string { return " hive-app[bot] " }, discardLogger()) + if got := g.HiveLogins(); len(got) != 1 || got[0] != "hive-app[bot]" { + t.Fatalf("logins = %v", got) + } + if got := newReviewThreadGuard(func() string { return "" }, func() string { return "" }, discardLogger()).HiveLogins(); got != nil { + t.Fatalf("no App login must yield no logins, got %v", got) + } + now := time.Now() + g.OnRefused(proxy.ReviewWriteRefusal{Agent: "quality", Repo: "cncf/techdocs", Number: 424, InReplyTo: "1", Body: "drafted", At: now}) + if due := openReviewFeedbackStore(discardLogger()).BlockedDraftsDue(feedbackTestKey, now, time.Hour); len(due) != 1 || due[0].Body != "drafted" { + t.Fatalf("refused reply not kept: %+v", due) + } +} diff --git a/src/crux/proxy/github_proxy.go b/src/crux/proxy/github_proxy.go index 5875dedfc4..c26dd24cb8 100644 --- a/src/crux/proxy/github_proxy.go +++ b/src/crux/proxy/github_proxy.go @@ -105,6 +105,9 @@ type GitHubProxy struct { referenceRepos map[string]ReferenceRepoPolicy referenceDefaults map[string]referenceDefaultBranch referenceLookup referenceLookupFunc + // reviewGuard holds the ownership seams for review-thread replies and + // own-comment deletes on the hive's own PRs (#19096, review_thread.go). + reviewGuard reviewGuardState // repoPaused reports whether a repo ("owner/repo", as ExtractRepo yields it) // is under an operator pause (#6203). Guarded because the dashboard can diff --git a/src/crux/proxy/github_proxy_mitm.go b/src/crux/proxy/github_proxy_mitm.go index c170eb5180..23682ab4a3 100644 --- a/src/crux/proxy/github_proxy_mitm.go +++ b/src/crux/proxy/github_proxy_mitm.go @@ -114,6 +114,13 @@ func (p *GitHubProxy) proxyHTTPHost(client net.Conn, upstream net.Conn, host str blockReason = reason blockCode = DenyReasonRepoAutoMergeOff blockJSON = true + } else if reason, refused := p.reviewThreadRefusal(req, agentName); !isLinear && refused { + // Review-thread replies, PR review comments and comment deletes + // (#19096): allowed only on the hive's own PR for the agent that + // opened it, or for the hive's own recent comment. + blocked = true + blockReason = reason + blockCode = DenyReasonReviewThread } else if !isLinear { if reason, kind, refused := p.writeSurfaceEnforceRefusal(agentName, req.Method, req.URL.Path, req.URL.RawQuery); refused { blocked = true @@ -279,6 +286,9 @@ func (p *GitHubProxy) proxyHTTPHost(client net.Conn, upstream net.Conn, host str detail = blockReason } p.recordViolation(agentName, req.Method, detail) + if agentName != internalCallerName && !isLinear { + p.noteRefusedReviewReply(req, agentName, detail) + } if writeSurfaceKind != "" { p.auditWriteRefused(agentName, writeSurfaceKind, req.Method, repoScopePath(req)) } diff --git a/src/crux/proxy/reference_repos.go b/src/crux/proxy/reference_repos.go index c738fda9f8..ad3df50d67 100644 --- a/src/crux/proxy/reference_repos.go +++ b/src/crux/proxy/reference_repos.go @@ -174,8 +174,15 @@ func ReferenceRepoDecision(pol ReferenceRepoPolicy, method, path, rawQuery strin m := refItemCommentsPath.FindStringSubmatch(path) n, _ := strconv.Atoi(m[1]) return referenceOwnItem, n, "" + case method == "POST" && reviewReplyPathRe.MatchString(path), + method == "DELETE" && ownCommentDeletePathRe.MatchString(path): + // A reply inside a review thread, or retracting the hive's own recent + // comment (#19096). The ownership checks (the hive's own PR and its + // opening agent, or the hive's own comment inside the retract window) + // are the review-thread gate's, which runs right after this one. + return referenceAllow, 0, "" } - return referenceDeny, 0, referenceRepoRefusal(pol, "only opening an issue or PR, forking it, pushing to the owner's fork and commenting on the hive's own items are ever allowed there — never merge, push to the default branch, label, assign, close or review") + return referenceDeny, 0, referenceRepoRefusal(pol, "only opening an issue or PR, forking it, pushing to the owner's fork, commenting on the hive's own items, replying in review threads on the hive's own PRs and retracting the hive's own recent comment are ever allowed there — never merge, push to the default branch, label, assign, close or review") } func referenceRepoRefusal(pol ReferenceRepoPolicy, why string) string { diff --git a/src/crux/proxy/review_thread.go b/src/crux/proxy/review_thread.go new file mode 100644 index 0000000000..2756ad845e --- /dev/null +++ b/src/crux/proxy/review_thread.go @@ -0,0 +1,361 @@ +package proxy + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" + "regexp" + "strconv" + "strings" + "sync" + "time" +) + +// Review-thread replies on the hive's own PRs (hivecommons/hive#19096). +// +// The review-feedback sweep (#19027) kicks the agent that opened a PR when a +// person leaves review comments on it. Answering those comments in place +// needs two REST routes the rule table never had, so both fell through to +// deny-by-default while the issue-comment route passed: +// +// - POST /repos/{o}/{r}/pulls/comments/{id}/replies (reply in a thread) +// - POST /repos/{o}/{r}/pulls/{n}/comments (PR review comment) +// +// They are allowed here, and only here, when the PR is one the hive's own +// agent opened (the audit trail's agent_pr_created entries, the same +// ownership source the sweep uses) and the caller is the agent that opened +// it. Any other PR, any other agent, and any PR the hive cannot attribute is +// refused. +// +// An agent may also retract its own mistake: DELETE of an issue comment or a +// review comment is allowed only when GitHub says the comment was written by +// the hive's own identity and it is younger than OwnCommentDeleteWindow. +// Anyone else's comment, and any older one, stays refused. A lookup that +// fails refuses (fail closed) and says so. + +// DenyReasonReviewThread is the 403 reason code for a refused review-thread +// reply, PR review comment or comment delete (see denial_message.go). +const DenyReasonReviewThread = "review_thread" + +// OwnCommentDeleteWindow is how long after creation the hive's own comment may +// be deleted by an agent. Long enough to notice and retract a mistake within +// one run, short enough that it never becomes a way to rewrite history. +const OwnCommentDeleteWindow = 15 * time.Minute + +// ownCommentClockSkew tolerates a comment timestamp slightly ahead of this +// host's clock; anything further in the future is treated as unknown. +const ownCommentClockSkew = time.Minute + +// reviewDraftBodyLimit bounds the body read from a refused reply so the +// drafted text can be handed to the sweep's needs-human note. +const reviewDraftBodyLimit = 16 * 1024 + +// Kinds of guarded review-thread write. +const ( + reviewWriteReply = "reply" + reviewWritePRComment = "pr_comment" + reviewWriteDelete = "delete" +) + +var ( + reviewReplyPathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/pulls/comments/(\d+)/replies$`) + reviewPRCommentPathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/pulls/(\d+)/comments$`) + ownCommentDeletePathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/(issues|pulls)/comments/(\d+)$`) +) + +// reviewThreadWrite is one classified guarded request. +type reviewThreadWrite struct { + kind string + repo string + // number is the PR for reviewWritePRComment (from the path). + number int + // commentID is the target comment for reviewWriteReply / reviewWriteDelete. + commentID string + // commentSurface is "issues" or "pulls" for reviewWriteDelete. + commentSurface string +} + +// classifyReviewThreadWrite reports whether (method, path) is one of the +// guarded routes. Every other request is untouched by this gate. +func classifyReviewThreadWrite(method, path string) (reviewThreadWrite, bool) { + switch method { + case http.MethodPost: + if m := reviewReplyPathRe.FindStringSubmatch(path); m != nil { + return reviewThreadWrite{kind: reviewWriteReply, repo: m[1], commentID: m[2]}, true + } + if m := reviewPRCommentPathRe.FindStringSubmatch(path); m != nil { + n, err := strconv.Atoi(m[2]) + if err != nil || n <= 0 { + return reviewThreadWrite{}, false + } + return reviewThreadWrite{kind: reviewWritePRComment, repo: m[1], number: n}, true + } + case http.MethodDelete: + if m := ownCommentDeletePathRe.FindStringSubmatch(path); m != nil { + return reviewThreadWrite{kind: reviewWriteDelete, repo: m[1], commentSurface: m[2], commentID: m[3]}, true + } + } + return reviewThreadWrite{}, false +} + +// ReviewWriteRefusal describes a refused reply on a PR the hive's own agent +// opened, so the review-feedback sweep can hand the drafted text to a person. +type ReviewWriteRefusal struct { + Agent string + Repo string + Number int + // InReplyTo is the review comment the reply answered, "" for a PR comment. + InReplyTo string + // Body is the drafted reply text (bounded), "" when unreadable. + Body string + Reason string + At time.Time +} + +// ReviewThreadGuard is what the hive supplies for the gate. +type ReviewThreadGuard struct { + // OwnPR returns the agent that opened repo#number, from the audit trail, + // and whether the hive's own agent opened it at all. + OwnPR func(repo string, number int) (agent string, ok bool) + // HiveLogins returns the GitHub logins that are the hive's own identity + // (the App bot). A reference repo's write Login is added by the proxy. + HiveLogins func() []string + // OnRefused, when set, receives each refused reply on a hive-owned PR. + OnRefused func(ReviewWriteRefusal) + // Now is the clock; nil is time.Now. + Now func() time.Time +} + +// reviewGuardState is the guarded copy the proxy holds. +type reviewGuardState struct { + mu sync.RWMutex + guard ReviewThreadGuard +} + +// SetReviewThreadGuard installs the ownership seams for review-thread replies +// and own-comment deletes (#19096). With no guard (or no OwnPR) every guarded +// route is refused, which is exactly the behaviour before this gate existed. +func (p *GitHubProxy) SetReviewThreadGuard(g ReviewThreadGuard) { + p.reviewGuard.mu.Lock() + p.reviewGuard.guard = g + p.reviewGuard.mu.Unlock() +} + +func (p *GitHubProxy) reviewThreadGuard() ReviewThreadGuard { + p.reviewGuard.mu.RLock() + defer p.reviewGuard.mu.RUnlock() + return p.reviewGuard.guard +} + +func (g ReviewThreadGuard) now() time.Time { + if g.Now != nil { + return g.Now() + } + return time.Now() +} + +// reviewThreadRefusalText is the agent-facing 403 body. It tells the agent to +// stop instead of probing other routes: a probe comment on a person's review +// is worse than an unanswered thread. +func reviewThreadRefusalText(why string) string { + return "review-thread write refused: " + why + ". Replies inside review threads and PR review comments are allowed only on a PR the hive's own agent opened, and only for the agent that opened it; deleting a comment is allowed only for the hive's own comment within " + OwnCommentDeleteWindow.String() + " of posting. Do NOT retry, do NOT post the reply as an issue comment instead, and NEVER post a test or probe comment. Stop here: the hive's review-feedback sweep hands your drafted reply to a person." +} + +// reviewThreadRefusal is the per-request gate the MITM loop calls for +// non-internal callers. It returns the refusal reason and true when the +// request must be blocked; a request that is not a guarded route returns +// false and is left to the rest of the chain (mode table, repo filter). +func (p *GitHubProxy) reviewThreadRefusal(req *http.Request, agentName string) (string, bool) { + w, ok := classifyReviewThreadWrite(req.Method, req.URL.Path) + if !ok { + return "", false + } + g := p.reviewThreadGuard() + if agentName == "" { + return reviewThreadRefusalText("the calling agent could not be identified"), true + } + if g.OwnPR == nil { + return reviewThreadRefusalText("this hive has no record of which PRs its agents opened"), true + } + if w.kind == reviewWriteDelete { + return p.ownCommentDeleteRefusal(req, agentName, w, g) + } + number := w.number + if w.kind == reviewWriteReply { + n, err := p.reviewCommentPR(req, agentName, w) + if err != nil { + return reviewThreadRefusalText(fmt.Sprintf("could not resolve which PR review comment %s belongs to (%v)", w.commentID, err)), true + } + number = n + } + owner, owned := g.OwnPR(w.repo, number) + if !owned { + return reviewThreadRefusalText(fmt.Sprintf("%s#%d was not opened by the hive's own agent", w.repo, number)), true + } + if !strings.EqualFold(owner, agentName) { + return reviewThreadRefusalText(fmt.Sprintf("%s#%d was opened by agent %s, not by %s", w.repo, number, owner, agentName)), true + } + return "", false +} + +// noteRefusedReviewReply is called for every blocked request, whichever gate +// refused it (this one, a reference-repo rule, the mode table, write-surface +// enforcement). When the request was a reply or PR review comment on a PR the +// hive's own agent opened, the drafted text is handed to the review-feedback +// sweep so it can post its needs-human note with the reply a person should +// place. The request body is left readable for the caller's drain. +func (p *GitHubProxy) noteRefusedReviewReply(req *http.Request, agentName, reason string) { + w, ok := classifyReviewThreadWrite(req.Method, req.URL.Path) + if !ok || w.kind == reviewWriteDelete { + return + } + g := p.reviewThreadGuard() + if g.OnRefused == nil || g.OwnPR == nil { + return + } + number := w.number + if w.kind == reviewWriteReply { + n, err := p.reviewCommentPR(req, agentName, w) + if err != nil { + return + } + number = n + } + if _, owned := g.OwnPR(w.repo, number); !owned { + return + } + body, inReplyTo := peekReviewDraft(req) + if w.kind == reviewWriteReply { + inReplyTo = w.commentID + } + g.OnRefused(ReviewWriteRefusal{Agent: agentName, Repo: w.repo, Number: number, InReplyTo: inReplyTo, Body: body, Reason: reason, At: g.now()}) +} + +// peekReviewDraft reads the JSON body of a reply ({"body": ..., "in_reply_to": +// ...}) without consuming it. +func peekReviewDraft(req *http.Request) (body, inReplyTo string) { + if req.Body == nil { + return "", "" + } + raw, err := io.ReadAll(io.LimitReader(req.Body, reviewDraftBodyLimit)) + req.Body = bodyReadCloser{Reader: io.MultiReader(bytes.NewReader(raw), req.Body), Closer: req.Body} + if err != nil { + return "", "" + } + var payload struct { + Body string `json:"body"` + InReplyTo json.RawMessage `json:"in_reply_to"` + } + if json.Unmarshal(raw, &payload) != nil { + return "", "" + } + return payload.Body, strings.Trim(string(payload.InReplyTo), `"`) +} + +// ownCommentDeleteRefusal allows DELETE only of the hive's own recent comment. +func (p *GitHubProxy) ownCommentDeleteRefusal(req *http.Request, agentName string, w reviewThreadWrite, g ReviewThreadGuard) (string, bool) { + meta, err := p.reviewCommentMeta(req, agentName, w.repo, w.commentSurface, w.commentID) + if err != nil { + return reviewThreadRefusalText(fmt.Sprintf("could not confirm comment %s is the hive's own (%v)", w.commentID, err)), true + } + logins := p.hiveLoginsFor(w.repo, g) + own := false + for _, l := range logins { + if l != "" && strings.EqualFold(l, meta.User.Login) { + own = true + break + } + } + if !own { + return reviewThreadRefusalText(fmt.Sprintf("comment %s was written by %s, not by the hive", w.commentID, meta.User.Login)), true + } + age := g.now().Sub(meta.CreatedAt) + if meta.CreatedAt.IsZero() || age < -ownCommentClockSkew { + return reviewThreadRefusalText(fmt.Sprintf("comment %s has no usable creation time", w.commentID)), true + } + if age > OwnCommentDeleteWindow { + return reviewThreadRefusalText(fmt.Sprintf("comment %s is %s old, past the %s retract window", w.commentID, age.Round(time.Second), OwnCommentDeleteWindow)), true + } + return "", false +} + +// hiveLoginsFor is the hive's identity on repo: the guard's logins plus the +// reference repo's write Login when repo is one. +func (p *GitHubProxy) hiveLoginsFor(repo string, g ReviewThreadGuard) []string { + var out []string + if g.HiveLogins != nil { + out = append(out, g.HiveLogins()...) + } + if pol, ok := p.ReferenceRepoPolicyFor(repo); ok && pol.Login != "" { + out = append(out, pol.Login) + } + return out +} + +// reviewCommentMetadata is the slice of a GitHub comment the gate reads. +type reviewCommentMetadata struct { + User struct { + Login string `json:"login"` + } `json:"user"` + CreatedAt time.Time `json:"created_at"` + PullRequestURL string `json:"pull_request_url"` +} + +// reviewCommentMeta GETs /repos/{repo}/{issues|pulls}/comments/{id}. +func (p *GitHubProxy) reviewCommentMeta(req *http.Request, agentName, repo, surface, id string) (reviewCommentMetadata, error) { + var meta reviewCommentMetadata + body, err := p.referenceLookupOrDefault()(referenceAPIBase(req)+"/repos/"+repo+"/"+surface+"/comments/"+id, p.reviewLookupToken(req, agentName, repo)) + if err != nil { + return meta, err + } + if err := json.Unmarshal(body, &meta); err != nil { + return meta, err + } + if meta.User.Login == "" { + return meta, fmt.Errorf("comment has no author") + } + return meta, nil +} + +// reviewCommentPR resolves a review comment to its PR number. +func (p *GitHubProxy) reviewCommentPR(req *http.Request, agentName string, w reviewThreadWrite) (int, error) { + meta, err := p.reviewCommentMeta(req, agentName, w.repo, "pulls", w.commentID) + if err != nil { + return 0, err + } + i := strings.LastIndex(meta.PullRequestURL, "/pulls/") + if i < 0 { + return 0, fmt.Errorf("comment carries no pull_request_url") + } + n, err := strconv.Atoi(meta.PullRequestURL[i+len("/pulls/"):]) + if err != nil || n <= 0 { + return 0, fmt.Errorf("unreadable pull_request_url %q", meta.PullRequestURL) + } + return n, nil +} + +// reviewLookupToken picks the credential for the gate's own GET: a reference +// repo's write token, else the agent's hub-held token, else the credential the +// request itself carries. All three are already on this request's path; none +// is borrowed from another agent. "" sends the GET unauthenticated. +func (p *GitHubProxy) reviewLookupToken(req *http.Request, agentName, repo string) string { + if pol, ok := p.ReferenceRepoPolicyFor(repo); ok { + if tok := p.referenceToken(pol); tok != "" { + return tok + } + } + if p.agentTokenSource != nil { + if tok, ok := p.agentTokenSource(agentName); ok && tok != "" { + return tok + } + } + auth := strings.TrimSpace(req.Header.Get("Authorization")) + for _, scheme := range []string{"token ", "bearer "} { + if len(auth) > len(scheme) && strings.EqualFold(auth[:len(scheme)], scheme) { + return strings.TrimSpace(auth[len(scheme):]) + } + } + return "" +} diff --git a/src/crux/proxy/review_thread_test.go b/src/crux/proxy/review_thread_test.go new file mode 100644 index 0000000000..ebeca77c54 --- /dev/null +++ b/src/crux/proxy/review_thread_test.go @@ -0,0 +1,405 @@ +package proxy + +import ( + "bufio" + "bytes" + "errors" + "fmt" + "io" + "log/slog" + "net" + "net/http" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/crux/agent" +) + +const ( + rtRepo = "cncf/techdocs" + rtPR = 424 + rtOwner = "quality" + rtHiveBot = "hive-app[bot]" + rtReplyID = "4616203214" + rtOtherPR = 99 + rtCommentA = "6988449875" +) + +// rtFixture is the fake GitHub the gate's own GETs read. +type rtFixture struct { + now time.Time + comments map[string]string // url suffix -> JSON + lookups []string + tokens []string + failAll bool +} + +func (f *rtFixture) lookup(url, token string) ([]byte, error) { + f.lookups = append(f.lookups, url) + f.tokens = append(f.tokens, token) + if f.failAll { + return nil, errors.New("GitHub answered 502") + } + for suffix, body := range f.comments { + if strings.HasSuffix(url, suffix) { + return []byte(body), nil + } + } + return nil, errors.New("GitHub answered 404") +} + +func newRTFixture(now time.Time) *rtFixture { + at := func(d time.Duration) string { return now.Add(-d).UTC().Format(time.RFC3339) } + return &rtFixture{now: now, comments: map[string]string{ + // A person's review comment on the hive's PR, and one on another PR. + "/repos/cncf/techdocs/pulls/comments/" + rtReplyID: fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q,"pull_request_url":"https://api.github.com/repos/cncf/techdocs/pulls/%d"}`, at(time.Hour), rtPR), + "/repos/cncf/techdocs/pulls/comments/777": fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q,"pull_request_url":"https://api.github.com/repos/cncf/techdocs/pulls/%d"}`, at(time.Hour), rtOtherPR), + "/repos/cncf/techdocs/pulls/comments/778": `{"user":{"login":"nate"},"created_at":"2026-01-01T00:00:00Z"}`, + // The hive's own probe comment, two minutes old. + "/repos/cncf/techdocs/issues/comments/" + rtCommentA: fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(2*time.Minute)), + // The hive's own comment, but an hour old. + "/repos/cncf/techdocs/issues/comments/100": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(time.Hour)), + // A person's comment, a minute old. + "/repos/cncf/techdocs/issues/comments/101": fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q}`, at(time.Minute)), + // The hive's own review comment, a minute old. + "/repos/cncf/techdocs/pulls/comments/102": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(time.Minute)), + // The hive's comment dated in the future (clock trouble): unknown. + "/repos/cncf/techdocs/issues/comments/103": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(-time.Hour)), + // No author at all. + "/repos/cncf/techdocs/issues/comments/104": `{"created_at":"2026-01-01T00:00:00Z"}`, + }} +} + +func rtOwnPR(repo string, number int) (string, bool) { + if strings.EqualFold(repo, rtRepo) && number == rtPR { + return rtOwner, true + } + return "", false +} + +func newRTProxy(t *testing.T, f *rtFixture, refused *[]ReviewWriteRefusal) *GitHubProxy { + t.Helper() + p := &GitHubProxy{logger: slog.New(slog.NewTextHandler(io.Discard, nil))} + p.referenceLookup = f.lookup + p.SetReviewThreadGuard(ReviewThreadGuard{ + OwnPR: rtOwnPR, + HiveLogins: func() []string { return []string{rtHiveBot} }, + OnRefused: func(r ReviewWriteRefusal) { + if refused != nil { + *refused = append(*refused, r) + } + }, + Now: func() time.Time { return f.now }, + }) + return p +} + +func rtReq(method, path, body string) *http.Request { + req, _ := http.NewRequest(method, "https://api.github.com"+path, strings.NewReader(body)) + req.Host = "api.github.com" + return req +} + +func TestReviewThreadRefusal_Matrix(t *testing.T) { + replyPath := "/repos/cncf/techdocs/pulls/comments/" + rtReplyID + "/replies" + cases := []struct { + name string + agent string + method string + path string + wantRefuse bool + wantWhy string + }{ + // Replies and PR review comments: the hive's PR, the agent that opened it. + {"reply on hive PR by owning agent", rtOwner, "POST", replyPath, false, ""}, + {"reply owner match is case-insensitive", "Quality", "POST", replyPath, false, ""}, + {"PR review comment by owning agent", rtOwner, "POST", "/repos/cncf/techdocs/pulls/424/comments", false, ""}, + {"reply by another agent", "scanner", "POST", replyPath, true, "opened by agent quality, not by scanner"}, + {"PR review comment by another agent", "scanner", "POST", "/repos/cncf/techdocs/pulls/424/comments", true, "not by scanner"}, + {"reply on a PR the hive did not open", rtOwner, "POST", "/repos/cncf/techdocs/pulls/comments/777/replies", true, "was not opened by the hive's own agent"}, + {"PR review comment on a PR the hive did not open", rtOwner, "POST", "/repos/cncf/techdocs/pulls/99/comments", true, "was not opened by the hive's own agent"}, + {"PR review comment on another repo", rtOwner, "POST", "/repos/cncf/toc/pulls/424/comments", true, "was not opened by the hive's own agent"}, + {"reply whose comment cannot be found", rtOwner, "POST", "/repos/cncf/techdocs/pulls/comments/5/replies", true, "could not resolve"}, + {"reply whose comment has no PR url", rtOwner, "POST", "/repos/cncf/techdocs/pulls/comments/778/replies", true, "no pull_request_url"}, + {"unidentified caller", "", "POST", replyPath, true, "could not be identified"}, + // Deletes: the hive's own comment inside the window only. + {"delete own recent issue comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/" + rtCommentA, false, ""}, + {"delete own recent review comment", "scanner", "DELETE", "/repos/cncf/techdocs/pulls/comments/102", false, ""}, + {"delete own old comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/100", true, "past the 15m0s retract window"}, + {"delete someone else's comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/101", true, "written by nate, not by the hive"}, + {"delete comment dated in the future", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/103", true, "no usable creation time"}, + {"delete comment with no author", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/104", true, "could not confirm"}, + {"delete unknown comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/1", true, "could not confirm"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + f := newRTFixture(time.Now()) + p := newRTProxy(t, f, nil) + reason, refused := p.reviewThreadRefusal(rtReq(tc.method, tc.path, `{"body":"x"}`), tc.agent) + if refused != tc.wantRefuse { + t.Fatalf("refused=%v want %v (reason %q)", refused, tc.wantRefuse, reason) + } + if tc.wantRefuse { + for _, want := range []string{tc.wantWhy, "NEVER post a test or probe comment", "Do NOT retry"} { + if !strings.Contains(reason, want) { + t.Fatalf("reason missing %q: %q", want, reason) + } + } + } + }) + } +} + +func TestReviewThreadRefusal_UnguardedRoutesUntouched(t *testing.T) { + f := newRTFixture(time.Now()) + p := newRTProxy(t, f, nil) + for _, rt := range []struct{ method, path string }{ + {"POST", "/repos/cncf/techdocs/issues/424/comments"}, + {"POST", "/repos/cncf/techdocs/pulls/424/reviews"}, + {"PATCH", "/repos/cncf/techdocs/issues/comments/1"}, + {"GET", "/repos/cncf/techdocs/pulls/comments/1"}, + {"DELETE", "/repos/cncf/techdocs/issues/424"}, + {"POST", "/repos/cncf/techdocs/pulls/0/comments"}, + } { + if reason, refused := p.reviewThreadRefusal(rtReq(rt.method, rt.path, ""), rtOwner); refused { + t.Errorf("%s %s must be left to the rest of the chain, got %q", rt.method, rt.path, reason) + } + } + if len(f.lookups) != 0 { + t.Fatalf("unguarded routes must not cost a lookup: %v", f.lookups) + } +} + +func TestReviewThreadRefusal_NoGuardRefusesEverything(t *testing.T) { + p := &GitHubProxy{logger: slog.New(slog.NewTextHandler(io.Discard, nil))} + for _, rt := range []struct{ method, path string }{ + {"POST", "/repos/cncf/techdocs/pulls/comments/1/replies"}, + {"POST", "/repos/cncf/techdocs/pulls/424/comments"}, + {"DELETE", "/repos/cncf/techdocs/issues/comments/1"}, + } { + reason, refused := p.reviewThreadRefusal(rtReq(rt.method, rt.path, ""), rtOwner) + if !refused || !strings.Contains(reason, "no record of which PRs") { + t.Errorf("%s %s with no guard: refused=%v reason=%q", rt.method, rt.path, refused, reason) + } + } +} + +func TestReviewThreadRefusal_LookupFailureFailsClosed(t *testing.T) { + f := newRTFixture(time.Now()) + f.failAll = true + p := newRTProxy(t, f, nil) + for _, path := range []string{"/repos/cncf/techdocs/pulls/comments/" + rtReplyID + "/replies", "/repos/cncf/techdocs/issues/comments/" + rtCommentA} { + method := "POST" + if strings.Contains(path, "issues/comments") { + method = "DELETE" + } + if _, refused := p.reviewThreadRefusal(rtReq(method, path, ""), rtOwner); !refused { + t.Errorf("%s %s must refuse when GitHub cannot be read", method, path) + } + } +} + +func TestReviewThreadRefusal_ReferenceRepoLoginCountsAsHive(t *testing.T) { + f := newRTFixture(time.Now()) + f.comments["/repos/cncf/techdocs/issues/comments/200"] = fmt.Sprintf(`{"user":{"login":"hive-owner"},"created_at":%q}`, f.now.Add(-time.Minute).UTC().Format(time.RFC3339)) + p := newRTProxy(t, f, nil) + pol := ReferenceRepoPolicy{Repo: rtRepo, Issues: true, PRs: true, Login: "hive-owner", Token: func() (string, bool) { return "ref-tok", true }} + p.SetReferenceRepos([]ReferenceRepoPolicy{pol}) + if reason, refused := p.reviewThreadRefusal(rtReq("DELETE", "/repos/cncf/techdocs/issues/comments/200", ""), rtOwner); refused { + t.Fatalf("the reference repo's write login is the hive's identity there: %q", reason) + } + if got := f.tokens[len(f.tokens)-1]; got != "ref-tok" { + t.Fatalf("lookup on a reference repo must use its write token, got %q", got) + } +} + +func TestReviewLookupToken_Preference(t *testing.T) { + p := &GitHubProxy{logger: slog.New(slog.NewTextHandler(io.Discard, nil))} + req := rtReq("POST", "/repos/o/r/pulls/1/comments", "") + if got := p.reviewLookupToken(req, rtOwner, "o/r"); got != "" { + t.Fatalf("no credential anywhere: got %q", got) + } + req.Header.Set("Authorization", "Bearer req-tok") + if got := p.reviewLookupToken(req, rtOwner, "o/r"); got != "req-tok" { + t.Fatalf("request credential: got %q", got) + } + req.Header.Set("Authorization", "token req-tok2") + if got := p.reviewLookupToken(req, rtOwner, "o/r"); got != "req-tok2" { + t.Fatalf("token scheme: got %q", got) + } + p.agentTokenSource = func(name string) (string, bool) { return "agent-" + name, name == rtOwner } + if got := p.reviewLookupToken(req, rtOwner, "o/r"); got != "agent-quality" { + t.Fatalf("hub-held agent token wins over the request's: got %q", got) + } + if got := p.reviewLookupToken(req, "scanner", "o/r"); got != "req-tok2" { + t.Fatalf("never another agent's token: got %q", got) + } +} + +func TestNoteRefusedReviewReply_KeepsDraftForHiveOwnedPROnly(t *testing.T) { + var refused []ReviewWriteRefusal + f := newRTFixture(time.Now()) + p := newRTProxy(t, f, &refused) + draft := `{"body":"Verified; fixed in abc123."}` + cases := []struct { + name string + method, path string + body string + wantKept bool + wantInReplyTo string + }{ + {"thread reply on hive PR", "POST", "/repos/cncf/techdocs/pulls/comments/" + rtReplyID + "/replies", draft, true, rtReplyID}, + {"PR review comment with in_reply_to", "POST", "/repos/cncf/techdocs/pulls/424/comments", `{"body":"b","in_reply_to":42}`, true, "42"}, + {"reply on someone else's PR", "POST", "/repos/cncf/techdocs/pulls/comments/777/replies", draft, false, ""}, + {"unresolvable reply", "POST", "/repos/cncf/techdocs/pulls/comments/5/replies", draft, false, ""}, + {"delete is never a draft", "DELETE", "/repos/cncf/techdocs/issues/comments/" + rtCommentA, "", false, ""}, + {"unguarded route", "POST", "/repos/cncf/techdocs/issues/424/comments", draft, false, ""}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + refused = nil + req := rtReq(tc.method, tc.path, tc.body) + p.noteRefusedReviewReply(req, "scanner", "refused for test") + if (len(refused) == 1) != tc.wantKept { + t.Fatalf("kept=%d want %v", len(refused), tc.wantKept) + } + if tc.wantKept { + r := refused[0] + if r.Repo != rtRepo || r.Number != rtPR || r.Agent != "scanner" || r.InReplyTo != tc.wantInReplyTo || r.Reason != "refused for test" || r.Body == "" { + t.Fatalf("refusal = %+v", r) + } + rest, _ := io.ReadAll(req.Body) + if string(rest) != tc.body { + t.Fatalf("request body must stay readable for the drain, got %q", rest) + } + } + }) + } +} + +func TestPeekReviewDraft_EdgeCases(t *testing.T) { + if b, r := peekReviewDraft(&http.Request{}); b != "" || r != "" { + t.Fatal("nil body yields nothing") + } + req, _ := http.NewRequest("POST", "https://api.github.com/x", bytes.NewReader([]byte("not json"))) + if b, _ := peekReviewDraft(req); b != "" { + t.Fatal("non-JSON body yields no draft") + } + if rest, _ := io.ReadAll(req.Body); string(rest) != "not json" { + t.Fatalf("body must be restored, got %q", rest) + } +} + +func TestReviewThreadRules_ModeTable(t *testing.T) { + converse := agent.AgentCapabilities{Converse: true} + cases := []struct { + name string + mode agent.AgentMode + caps agent.AgentCapabilities + method string + path string + want bool + }{ + {"reply at issues+prs", agent.ModeIssuesAndPRs, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/comments/1/replies", true}, + {"reply at issues-only", agent.ModeIssuesOnly, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/comments/1/replies", false}, + {"reply with converse", agent.ModeAdvisory, converse, "POST", "/repos/o/r/pulls/comments/1/replies", true}, + {"pr comment at issues+prs", agent.ModeIssuesAndPRs, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/7/comments", true}, + {"pr comment at advisory", agent.ModeAdvisory, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/7/comments", false}, + {"delete comment at issues-only", agent.ModeIssuesOnly, agent.AgentCapabilities{}, "DELETE", "/repos/o/r/issues/comments/1", true}, + {"delete review comment at issues-only", agent.ModeIssuesOnly, agent.AgentCapabilities{}, "DELETE", "/repos/o/r/pulls/comments/1", true}, + {"delete comment at advisory", agent.ModeAdvisory, converse, "DELETE", "/repos/o/r/issues/comments/1", false}, + {"edit comment stays denied", agent.ModeIssuesPRsMerge, agent.AgentCapabilities{}, "PATCH", "/repos/o/r/pulls/comments/1", false}, + } + for _, tc := range cases { + if got := AllowedByModeCaps(tc.mode, tc.caps, tc.method, tc.path); got != tc.want { + t.Errorf("%s: AllowedByModeCaps=%v want %v", tc.name, got, tc.want) + } + } +} + +func TestReferenceRepoDecision_ReviewThreadRoutes(t *testing.T) { + both := ReferenceRepoPolicy{Repo: "hivecommons/docs", Issues: true, PRs: true} + ro := ReferenceRepoPolicy{Repo: "hivecommons/docs"} + cases := []struct { + name string + pol ReferenceRepoPolicy + method string + path string + want referenceDecision + }{ + {"reply defers to the review-thread gate", both, "POST", "/repos/hivecommons/docs/pulls/comments/5/replies", referenceAllow}, + {"delete issue comment defers to the gate", both, "DELETE", "/repos/hivecommons/docs/issues/comments/5", referenceAllow}, + {"delete review comment defers to the gate", both, "DELETE", "/repos/hivecommons/docs/pulls/comments/5", referenceAllow}, + {"pr review comment keeps the own-item check", both, "POST", "/repos/hivecommons/docs/pulls/9/comments", referenceOwnItem}, + {"read-only still refuses replies", ro, "POST", "/repos/hivecommons/docs/pulls/comments/5/replies", referenceDeny}, + {"read-only still refuses deletes", ro, "DELETE", "/repos/hivecommons/docs/issues/comments/5", referenceDeny}, + {"edit comment stays refused", both, "PATCH", "/repos/hivecommons/docs/issues/comments/5", referenceDeny}, + } + for _, tc := range cases { + if got, _, reason := ReferenceRepoDecision(tc.pol, tc.method, tc.path, ""); got != tc.want { + t.Errorf("%s: decision=%v want %v (%q)", tc.name, got, tc.want, reason) + } + } + if !referenceWriteAllowedByMode(agent.ModeIssuesOnly, "POST", "/repos/hivecommons/docs/pulls/comments/5/replies") { + t.Error("a reference-repo reply needs only the comment tier") + } +} + +// End to end through the MITM loop: the agent that opened the PR gets its PR +// review comment forwarded; another agent is refused with the review_thread +// reason and its drafted reply is kept for the sweep. +func TestProxyHTTP_ReviewThreadGate(t *testing.T) { + cases := []struct { + name string + agentName string + wantCode int + wantKept bool + }{ + {"owning agent forwarded", rtOwner, http.StatusCreated, false}, + {"other agent refused, draft kept", "scanner", http.StatusForbidden, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var refused []ReviewWriteRefusal + f := newRTFixture(time.Now()) + p := newTestProxy() + p.referenceLookup = f.lookup + p.SetReviewThreadGuard(ReviewThreadGuard{ + OwnPR: rtOwnPR, + OnRefused: func(r ReviewWriteRefusal) { refused = append(refused, r) }, + Now: func() time.Time { return f.now }, + }) + clientConn, proxyClient := net.Pipe() + upstreamConn, proxyUpstream := net.Pipe() + defer clientConn.Close() + defer upstreamConn.Close() + go p.proxyHTTP(proxyClient, proxyUpstream, tc.agentName, agent.ModeIssuesAndPRs, agent.AgentCapabilities{}) + body := `{"body":"Verified; fixed in abc123.","in_reply_to":` + rtReplyID + `}` + go func() { + fmt.Fprintf(clientConn, "POST /repos/cncf/techdocs/pulls/424/comments HTTP/1.1\r\nHost: api.github.com\r\nContent-Type: application/json\r\nContent-Length: %d\r\n\r\n%s", len(body), body) + }() + if tc.wantCode == http.StatusCreated { + go answerOnce(upstreamConn, http.StatusCreated) + resp, err := http.ReadResponse(bufio.NewReader(clientConn), nil) + if err != nil { + t.Fatalf("read response: %v", err) + } + if resp.StatusCode != tc.wantCode { + t.Fatalf("status = %d, want %d", resp.StatusCode, tc.wantCode) + } + } else { + raw := readRefusal(t, clientConn) + if !strings.Contains(raw, "403") || !strings.Contains(raw, DenyReasonReviewThread) { + t.Fatalf("want a review_thread 403, got:\n%s", raw) + } + } + if (len(refused) == 1) != tc.wantKept { + t.Fatalf("kept drafts = %d, want kept=%v", len(refused), tc.wantKept) + } + if tc.wantKept && (refused[0].Body != "Verified; fixed in abc123." || refused[0].InReplyTo != rtReplyID) { + t.Fatalf("draft = %+v", refused[0]) + } + }) + } +} diff --git a/src/crux/proxy/rules.go b/src/crux/proxy/rules.go index e1a8b9ca6b..eef77e7c21 100644 --- a/src/crux/proxy/rules.go +++ b/src/crux/proxy/rules.go @@ -170,6 +170,16 @@ var rules = []ProxyRule{ // additional way in. {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/\d+/reviews`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, {PathPattern: regexp.MustCompile(`^(?:/api/v1)?/repos/[^/]+/[^/]+/pulls/\d+/reviews`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, + // Answering review feedback in place (#19096): a reply inside a review + // thread and a PR review comment. Same tier as a review. These rules only + // say WHICH modes may; the review-thread gate (review_thread.go) runs first + // and refuses both unless the PR is one the hive's own agent opened and the + // caller is that agent. + {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/comments/\d+/replies$`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, + {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/\d+/comments$`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, + // Retracting the hive's own comment (#19096). The review-thread gate refuses + // anyone else's comment and any comment older than OwnCommentDeleteWindow. + {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/(?:issues|pulls)/comments/\d+$`), Method: "DELETE", MinMode: agent.ModeIssuesOnly}, {PathPattern: regexp.MustCompile(`^(?:/api/v4)?/projects/.+?/merge_requests/\d+/notes`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, {PathPattern: regexp.MustCompile(`^(?:/api/v4)?/projects/.+?/merge_requests/\d+/discussions`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, diff --git a/src/docs/github-write-surface.md b/src/docs/github-write-surface.md index a563f2deb6..df7d752198 100644 --- a/src/docs/github-write-surface.md +++ b/src/docs/github-write-surface.md @@ -265,6 +265,9 @@ push a topic branch to the owner's fork, open a PR from that fork, comment on the hive's own issue or PR — sent as the hive owner's own GitHub account (connected once in Settings, [#18197](https://github.com/hivecommons/hive/issues/18197)) or, on a hand-written entry, a `write_token_file`; never as the hive's App. +Replying in a review thread on the hive's own PR and retracting the hive's +own recent comment are allowed under the +[review-thread gate](#review-thread-replies-on-the-hives-own-prs). Merge, default-branch push, labels, assignees, reviews, closing others' items and anything on the fork other than a push stay refused. The relays never act on a reference repo, so a lane under `write_surface.enforce` cannot @@ -272,6 +275,32 @@ write to one. See the [operator reference](operator-reference/README.md#configuration-blocks) and [Writing to repos you do not manage](agent-configuration.md#writing-to-repos-you-do-not-manage-the-two-lanes). +## Review-thread replies on the hive's own PRs + +When a person reviews a PR the hive's own agent opened, the review-feedback +sweep ([#19027](https://github.com/hivecommons/hive/issues/19027)) kicks that +agent to answer. The proxy lets it answer in place, and nothing wider +([#19096](https://github.com/hivecommons/hive/issues/19096), +`src/crux/proxy/review_thread.go`): + +| Route | Allowed when | +| --- | --- | +| `POST /repos/{o}/{r}/pulls/comments/{id}/replies` | the comment's PR was opened by the hive's own agent (audit trail `agent_pr_created`, the sweep's ownership source) and the caller is the agent that opened it | +| `POST /repos/{o}/{r}/pulls/{n}/comments` | the same: hive-opened PR, opening agent only | +| `DELETE /repos/{o}/{r}/issues/comments/{id}`, `DELETE /repos/{o}/{r}/pulls/comments/{id}` | GitHub reports the comment was written by the hive's own identity (the App bot, or a reference repo's write login) and it is younger than `OwnCommentDeleteWindow` (15 minutes) | + +Any other PR, any other agent, anyone else's comment, an older comment, and +any lookup that fails are refused with the `review_thread` reason, and the +agent is told to stop rather than probe another route. The mode tier still +applies on top (replies and PR review comments at `ISSUES_AND_PRS` or with +`converse`, deletes at `ISSUES_ONLY`). On a reference repo the same gate runs +after the reference-repo rules. When a reply on a hive-opened PR is refused by +any gate, the proxy keeps the drafted text and the sweep posts it in its +needs-human note, at most once per `HIVE_REVIEW_FEEDBACK_WINDOW`, so a person +can place it. The GraphQL `addPullRequestReviewThreadReply` mutation carries +only node ids and stays on the mode ladder (conversation bucket); this gate is +REST-only. + ## Enforcing the write surface `write_surface.enforce` lists the lanes whose **direct** GitHub writes from the diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index 94bc8390d5..449b2e10e0 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -119,7 +119,7 @@ The labels the hive applies instead of `hold` ([#18468](https://github.com/hivec | `ready-for-review` | Hive's work is done; a maintainer reviews, then removes this label to let it merge. | The ACMM level gate (L3-L5, and cross-repo outreach at every level). | | `decision-needed` | Hive is blocked on a human decision; a maintainer decides (see hive's comment). | The #5117 self-authorization gate, the #9665 reporter-trust gate (with `needs-human`), the holdguard re-hold, and an owner-only delegated decision (with `needs-owner`). | -Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. Neither label stops the hive from answering review feedback: when a person leaves an inline comment, a review (`COMMENTED` or `CHANGES_REQUESTED`) or a comment addressed to the hive on a PR the hive's own agent opened, that agent is kicked to verify the claim and push a signed revision or reply with evidence, whether the PR is a draft, held, or in a repo the hive does not manage ([#19027](https://github.com/hivecommons/hive/issues/19027); `src/cmd/hive/review_feedback_wire.go`, `src/pkg/reviewfeedback/reviewfeedback.go`). A hold means do not merge, not do not respond. A burst of comments is coalesced into one kick after `HIVE_REVIEW_FEEDBACK_DEBOUNCE` (default 3m); comments that arrive while the agent works get their own follow-up kick; each PR is capped at `HIVE_REVIEW_FEEDBACK_WINDOW_CAP` kicks (default 12) per `HIVE_REVIEW_FEEDBACK_WINDOW` (default 24h), the cap posts a needs-human note, and a person's next comment resets it; `HIVE_REVIEW_FEEDBACK_MAX_ITEMS` (default 30) bounds one brief. Set `HIVE_REVIEW_FEEDBACK_RESPONSE=off` to disable the sweep. A comment that states a rule or a source of truth for future work is also captured into the hive's knowledge with its provenance, gated on the reviewer's association, and acknowledged on the PR ([#19046](https://github.com/hivecommons/hive/issues/19046); see [review-feedback-rules.md](../review-feedback-rules.md)). +Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. Neither label stops the hive from answering review feedback: when a person leaves an inline comment, a review (`COMMENTED` or `CHANGES_REQUESTED`) or a comment addressed to the hive on a PR the hive's own agent opened, that agent is kicked to verify the claim and push a signed revision or reply with evidence, whether the PR is a draft, held, or in a repo the hive does not manage ([#19027](https://github.com/hivecommons/hive/issues/19027); `src/cmd/hive/review_feedback_wire.go`, `src/pkg/reviewfeedback/reviewfeedback.go`). A hold means do not merge, not do not respond. A burst of comments is coalesced into one kick after `HIVE_REVIEW_FEEDBACK_DEBOUNCE` (default 3m); comments that arrive while the agent works get their own follow-up kick; each PR is capped at `HIVE_REVIEW_FEEDBACK_WINDOW_CAP` kicks (default 12) per `HIVE_REVIEW_FEEDBACK_WINDOW` (default 24h), the cap posts a needs-human note, and a person's next comment resets it; `HIVE_REVIEW_FEEDBACK_MAX_ITEMS` (default 30) bounds one brief. Set `HIVE_REVIEW_FEEDBACK_RESPONSE=off` to disable the sweep. A comment that states a rule or a source of truth for future work is also captured into the hive's knowledge with its provenance, gated on the reviewer's association, and acknowledged on the PR ([#19046](https://github.com/hivecommons/hive/issues/19046); see [review-feedback-rules.md](../review-feedback-rules.md)). The kicked agent replies inside each thread with the replies endpoint, which the proxy allows only on the hive's own PR and only for the agent that opened it; it may delete its own comment within 15 minutes, never anyone else's, and is told never to post test or probe comments. If a reply is refused, the agent stops, the proxy keeps the drafted reply, and the sweep posts it in a needs-human note for a person to place ([#19096](https://github.com/hivecommons/hive/issues/19096); `src/crux/proxy/review_thread.go`, [GitHub write surface](../github-write-surface.md#review-thread-replies-on-the-hives-own-prs)). **Migration.** On boot, Hive creates both labels (with their descriptions) in each active repository and swaps a literal `hold` for the matching gate label only when the newest `hold` event is a `labeled` by the Hive App **and** an App-authored gate notice is on the thread (level-hold notice → `ready-for-review`; reporter-trust, #5117, holdguard or owner-only decision notice → `decision-needed`). It adds the gate label before removing `hold` and leaves one `` comment. A `hold` a person applied (or re-applied) is never touched. Bounded to 50 items per repository per boot (`src/pkg/github/hive_gate_label_migration.go`). diff --git a/src/pkg/reviewfeedback/reviewfeedback.go b/src/pkg/reviewfeedback/reviewfeedback.go index ffc12081a8..8760895748 100644 --- a/src/pkg/reviewfeedback/reviewfeedback.go +++ b/src/pkg/reviewfeedback/reviewfeedback.go @@ -61,6 +61,10 @@ const ( bodyRunes = 800 // handledRetention is how long a PR's record is kept after its last kick. handledRetention = 45 * 24 * time.Hour + // maxBlockedDrafts bounds the refused replies held per PR. + maxBlockedDrafts = DefaultMaxItems + // draftRunes bounds each drafted reply quoted into the needs-human note. + draftRunes = 2000 ) // Verdicts of Plan. @@ -139,6 +143,20 @@ type PRState struct { // Pending is the reply check owed for the last kick that carried // captured rules (hivecommons/hive#19048). Pending *PendingReply `json:"pending,omitempty"` + // BlockedDrafts are replies the agent drafted that the proxy refused + // (#19096); the next pass posts them in a needs-human note. + BlockedDrafts []ReplyDraft `json:"blocked_drafts,omitempty"` + // BlockedNotedAt is when drafted replies were last handed to a person. + BlockedNotedAt time.Time `json:"blocked_noted_at,omitempty"` +} + +// ReplyDraft is one reply the PR's agent tried to post and could not. +type ReplyDraft struct { + // InReplyTo is the review comment the reply answered, "" for a PR comment. + InReplyTo string `json:"in_reply_to,omitempty"` + Body string `json:"body"` + Agent string `json:"agent,omitempty"` + At time.Time `json:"at"` } // PendingReply is the rules a kick promised to be named in the agent's reply. @@ -397,6 +415,68 @@ func (s *Store) MarkNeedsHuman(key string, now time.Time) (bool, error) { return true, s.saveLocked(now) } +// RecordBlockedReply keeps a reply the proxy refused so the next pass can hand +// it to a person (#19096). An identical draft (same target, same text) is kept +// once, and at most maxBlockedDrafts are held per PR. +func (s *Store) RecordBlockedReply(key string, d ReplyDraft) error { + d.Body = strings.TrimSpace(d.Body) + if d.Body == "" { + return nil + } + s.mu.Lock() + defer s.mu.Unlock() + st := s.get(key) + for _, have := range st.BlockedDrafts { + if have.InReplyTo == d.InReplyTo && have.Body == d.Body { + return nil + } + } + if len(st.BlockedDrafts) >= maxBlockedDrafts { + return nil + } + st.BlockedDrafts = append(st.BlockedDrafts, d) + if st.LastKick.IsZero() { + st.LastKick = d.At + } + return s.saveLocked(d.At) +} + +// BlockedDraftsDue returns the refused replies waiting for a person, or nil +// while the last hand-off is younger than window (so a retrying agent cannot +// turn into one note per pass). +func (s *Store) BlockedDraftsDue(key string, now time.Time, window time.Duration) []ReplyDraft { + s.mu.Lock() + defer s.mu.Unlock() + st := s.PRs[key] + if st == nil || len(st.BlockedDrafts) == 0 { + return nil + } + if !st.BlockedNotedAt.IsZero() && now.Sub(st.BlockedNotedAt) < window { + return nil + } + return append([]ReplyDraft(nil), st.BlockedDrafts...) +} + +// MarkBlockedNoted records that drafts were handed to a person and drops them. +func (s *Store) MarkBlockedNoted(key string, posted []ReplyDraft, now time.Time) error { + s.mu.Lock() + defer s.mu.Unlock() + st := s.get(key) + done := map[string]bool{} + for _, d := range posted { + done[d.InReplyTo+"\x00"+d.Body] = true + } + kept := st.BlockedDrafts[:0] + for _, d := range st.BlockedDrafts { + if !done[d.InReplyTo+"\x00"+d.Body] { + kept = append(kept, d) + } + } + st.BlockedDrafts = kept + st.BlockedNotedAt = now + return s.saveLocked(now) +} + // NeedsHumanNoted reports whether the note was already posted for key. func (s *Store) NeedsHumanNoted(key string) bool { s.mu.Lock() @@ -465,7 +545,7 @@ func BuildBriefWithRules(repo string, number int, headRef, writingGuide string, b.WriteString(" 2. In a thread with several messages, apply the LATEST position: a later reply can refine or change what the first comment meant (a different target, a different number). Reply to the latest message.\n") b.WriteString(" 3. If the reviewer is right: fix it on the SAME branch (gh pr checkout, edit, git commit -s, git push). No replacement PR.\n") b.WriteString(" 4. If the reviewer is wrong or it is a judgment call: reply politely with the evidence. Never argue to defend a score or to please the reviewer; accuracy is the only goal.\n") - b.WriteString(" 5. Reply inside each thread (gh api repos/OWNER/REPO/pulls/N/comments/ID/replies), or on the PR for review and conversation comments. Each reply says what you verified, what you changed and in which commit, and what you left unchanged and why.\n") + b.WriteString(" 5. Reply inside each thread with the replies endpoint: gh api -X POST repos/OWNER/REPO/pulls/comments/ID/replies -f body=... where ID is the newest message in the thread. Answer review summaries and conversation comments with one PR comment. Each reply says what you verified, what you changed and in which commit, and what you left unchanged and why.\n") if len(rules) == 0 { b.WriteString(" 6. Rules, not only corrections. If a comment states a rule or a source of truth for future assessments (for example which file is authoritative for ownership), record it durably: write a knowledge fact in the hive's own knowledge store with `hivectl knowledge create --file fact.yaml` (title, body, tags, and the PR comment URL as the source), then say so in your reply. If the right home for the rule is another project's repo (for example its criteria files), do NOT write there: propose the exact text in your reply and say a person needs to place it. If hivectl cannot write, say so in the reply instead of dropping the rule.\n") } else { @@ -483,6 +563,8 @@ func BuildBriefWithRules(repo string, number int, headRef, writingGuide string, } } fmt.Fprintf(&b, " 7. End every reply set with one hidden line so these comments are not routed again: %s\n", github.FeedbackHandledMarker(feedbackIDs(items))) + b.WriteString("Never post a test, probe or placeholder comment to check permissions: every comment you post is public on a person's review. If you post a comment by mistake you may delete your own comment within a few minutes (gh api -X DELETE repos/OWNER/REPO/issues/comments/ID or .../pulls/comments/ID); never anyone else's.\n") + b.WriteString("If a reply or any other write is refused (HTTP 403 from the hive proxy), STOP: do not retry, do not post the reply some other way (for example as an issue comment), and do not probe other routes. The hive keeps the reply you drafted and posts it in a needs-human note so a person can place it.\n") b.WriteString("If you cannot push (no write access to the branch), say so in a PR comment that names what you would change, and stop.\n") b.WriteString("After replying, STOP. Do not poll CI or wait for the reviewer. More feedback that arrives while you work is sent as a separate follow-up.\n\n") b.WriteString("Style: plain sentences, no em-dashes, no raw @mentions of people (put handles in backticks), and follow the hive's writing guide.\n") @@ -566,11 +648,24 @@ func truncate(s string, n int) string { return s } -// NeedsHumanNote renders the one-time PR comment posted when the feedback -// cannot be routed to an agent. -func NeedsHumanNote(reason string, items []github.FeedbackItem) string { +// NeedsHumanNote renders the PR comment posted when the feedback cannot be +// routed to an agent, or when the agent's replies were refused (drafts set): +// then each drafted reply is quoted as text for a person to place. +func NeedsHumanNote(reason string, items []github.FeedbackItem, drafts []ReplyDraft) string { var b strings.Builder b.WriteString(github.FeedbackNeedsHumanMarker + "\n") + if len(drafts) > 0 { + b.WriteString("The hive's agent answered review feedback on this PR but could not post its replies: " + reason + ". A person needs to place them. Each drafted reply is quoted below as written; check it before posting.\n") + for _, d := range drafts { + if d.InReplyTo != "" { + fmt.Fprintf(&b, "\nReply to review comment %s:\n", d.InReplyTo) + } else { + b.WriteString("\nPR comment:\n") + } + writeFenced(&b, d.Body, draftRunes) + } + return b.String() + } b.WriteString("The hive saw review feedback on this PR but could not hand it to an agent: " + reason + ". A person needs to look at the open threads.\n") for _, it := range items { fmt.Fprintf(&b, "\n- %s", it.URL) diff --git a/src/pkg/reviewfeedback/reviewfeedback_test.go b/src/pkg/reviewfeedback/reviewfeedback_test.go index 94666f19da..3752bd3722 100644 --- a/src/pkg/reviewfeedback/reviewfeedback_test.go +++ b/src/pkg/reviewfeedback/reviewfeedback_test.go @@ -3,6 +3,7 @@ package reviewfeedback import ( "os" "path/filepath" + "strconv" "strings" "testing" "time" @@ -285,7 +286,7 @@ func TestLimitsNormalized_FillsInvalidKnobs(t *testing.T) { } func TestNeedsHumanNote_CarriesMarkerReasonAndLinks(t *testing.T) { - note := NeedsHumanNote("no agent", []github.FeedbackItem{item("inline:1"), item("inline:2")}) + note := NeedsHumanNote("no agent", []github.FeedbackItem{item("inline:1"), item("inline:2")}, nil) for _, want := range []string{github.FeedbackNeedsHumanMarker, "no agent", "https://example.invalid/inline:1", "https://example.invalid/inline:2"} { if !strings.Contains(note, want) { t.Errorf("note missing %q", want) @@ -334,6 +335,75 @@ func TestCheckReply(t *testing.T) { } } +func TestBlockedReplies_RecordDedupeDueAndMark(t *testing.T) { + dir := t.TempDir() + s, _ := Open(dir) + now := time.Now() + key := "o/r#7" + const window = 24 * time.Hour + if got := s.BlockedDraftsDue(key, now, window); got != nil { + t.Fatalf("no drafts yet, got %v", got) + } + cases := []struct { + name string + d ReplyDraft + }{ + {"thread reply", ReplyDraft{InReplyTo: "11", Body: "fixed in abc123", Agent: "quality", At: now}}, + {"duplicate is kept once", ReplyDraft{InReplyTo: "11", Body: " fixed in abc123 ", Agent: "quality", At: now}}, + {"pr comment", ReplyDraft{Body: "summary reply", Agent: "quality", At: now}}, + {"empty body ignored", ReplyDraft{InReplyTo: "12", Body: " ", At: now}}, + } + for _, tc := range cases { + if err := s.RecordBlockedReply(key, tc.d); err != nil { + t.Fatalf("%s: %v", tc.name, err) + } + } + due := s.BlockedDraftsDue(key, now, window) + if len(due) != 2 { + t.Fatalf("due = %d drafts, want 2 (deduped, empty dropped): %+v", len(due), due) + } + reloaded, err := Open(dir) + if err != nil || len(reloaded.BlockedDraftsDue(key, now, window)) != 2 { + t.Fatalf("drafts must survive a reload: err=%v", err) + } + if err := s.MarkBlockedNoted(key, due, now); err != nil { + t.Fatal(err) + } + if got := s.BlockedDraftsDue(key, now, window); got != nil { + t.Fatalf("posted drafts must be dropped, got %v", got) + } + _ = s.RecordBlockedReply(key, ReplyDraft{InReplyTo: "13", Body: "later draft", At: now.Add(time.Minute)}) + if got := s.BlockedDraftsDue(key, now.Add(time.Hour), window); got != nil { + t.Fatalf("a new draft inside the window must wait, got %v", got) + } + if got := s.BlockedDraftsDue(key, now.Add(window+time.Minute), window); len(got) != 1 { + t.Fatalf("after the window the waiting draft is due, got %v", got) + } +} + +func TestRecordBlockedReply_BoundedPerPR(t *testing.T) { + s, _ := Open(t.TempDir()) + now := time.Now() + for i := 0; i < maxBlockedDrafts+5; i++ { + _ = s.RecordBlockedReply("o/r#1", ReplyDraft{InReplyTo: strconv.Itoa(i), Body: "draft " + strconv.Itoa(i), At: now}) + } + if got := len(s.BlockedDraftsDue("o/r#1", now, time.Hour)); got != maxBlockedDrafts { + t.Fatalf("held %d drafts, want cap %d", got, maxBlockedDrafts) + } +} + +func TestNeedsHumanNote_WithDraftsQuotesEachReplyAsText(t *testing.T) { + note := NeedsHumanNote("the proxy refused the reply", nil, []ReplyDraft{ + {InReplyTo: "4616203214", Body: "Verified; fixed in abc123. ```nested```"}, + {Body: "Thanks, all threads addressed."}, + }) + for _, want := range []string{github.FeedbackNeedsHumanMarker, "could not post its replies", "the proxy refused the reply", "Reply to review comment 4616203214", "PR comment:", "```text", "'''nested'''"} { + if !strings.Contains(note, want) { + t.Errorf("note missing %q:\n%s", want, note) + } + } +} + func TestStorePendingReplyPersistsAndMerges(t *testing.T) { dir := t.TempDir() s, _ := Open(dir) @@ -356,3 +426,13 @@ func TestStorePendingReplyPersistsAndMerges(t *testing.T) { t.Fatal("pending not cleared") } } + +func TestBuildBrief_RepliesEndpointAndNoProbeComments(t *testing.T) { + brief := BuildBrief("o/r", 1, "", "", []github.FeedbackItem{item("inline:1")}) + for _, want := range []string{"pulls/comments/ID/replies", "Never post a test, probe or placeholder comment", "If a reply or any other write is refused", "STOP"} { + if !strings.Contains(brief, want) { + t.Errorf("brief missing %q", want) + } + } + } +} From aa6b06334d6a83942f5b703a6b43fa840a1b2ac7 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 14:34:28 -0500 Subject: [PATCH 2/7] =?UTF-8?q?=F0=9F=90=9B=20fix:=20keep=20the=20review-t?= =?UTF-8?q?hread=20mode=20rules=20out=20of=20rules.go=20for=20its=20size?= =?UTF-8?q?=20ratchet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #19096 Signed-off-by: Andy Anderson --- src/crux/proxy/review_thread.go | 17 +++++++++++++++++ src/crux/proxy/rules.go | 10 ---------- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/src/crux/proxy/review_thread.go b/src/crux/proxy/review_thread.go index 2756ad845e..b955b61ad5 100644 --- a/src/crux/proxy/review_thread.go +++ b/src/crux/proxy/review_thread.go @@ -11,6 +11,8 @@ import ( "strings" "sync" "time" + + "github.com/hivecommons/hive/crux/agent" ) // Review-thread replies on the hive's own PRs (hivecommons/hive#19096). @@ -65,6 +67,21 @@ var ( ownCommentDeletePathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/(issues|pulls)/comments/(\d+)$`) ) +// The mode-table rules for the guarded routes. They only say WHICH modes may: +// the review-thread gate runs first and refuses the reply routes unless the PR +// is the hive's own and the caller opened it, and a delete unless the comment +// is the hive's own and recent. Replies and PR review comments sit at the tier +// of a review (ISSUES_AND_PRS or converse); a delete at ISSUES_ONLY. No other +// rule matches these (method, path) pairs, so appending keeps first-match-wins +// order intact; they live here so rules.go stays inside its size ratchet. +func init() { + rules = append(rules, + ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/comments/\d+/replies$`), Method: http.MethodPost, MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, + ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/\d+/comments$`), Method: http.MethodPost, MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, + ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/(?:issues|pulls)/comments/\d+$`), Method: http.MethodDelete, MinMode: agent.ModeIssuesOnly}, + ) +} + // reviewThreadWrite is one classified guarded request. type reviewThreadWrite struct { kind string diff --git a/src/crux/proxy/rules.go b/src/crux/proxy/rules.go index eef77e7c21..e1a8b9ca6b 100644 --- a/src/crux/proxy/rules.go +++ b/src/crux/proxy/rules.go @@ -170,16 +170,6 @@ var rules = []ProxyRule{ // additional way in. {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/\d+/reviews`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, {PathPattern: regexp.MustCompile(`^(?:/api/v1)?/repos/[^/]+/[^/]+/pulls/\d+/reviews`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, - // Answering review feedback in place (#19096): a reply inside a review - // thread and a PR review comment. Same tier as a review. These rules only - // say WHICH modes may; the review-thread gate (review_thread.go) runs first - // and refuses both unless the PR is one the hive's own agent opened and the - // caller is that agent. - {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/comments/\d+/replies$`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, - {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/\d+/comments$`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, - // Retracting the hive's own comment (#19096). The review-thread gate refuses - // anyone else's comment and any comment older than OwnCommentDeleteWindow. - {PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/(?:issues|pulls)/comments/\d+$`), Method: "DELETE", MinMode: agent.ModeIssuesOnly}, {PathPattern: regexp.MustCompile(`^(?:/api/v4)?/projects/.+?/merge_requests/\d+/notes`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, {PathPattern: regexp.MustCompile(`^(?:/api/v4)?/projects/.+?/merge_requests/\d+/discussions`), Method: "POST", MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, From 437946c86d5e25b3642d6f46191303c1880f1a35 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 15:33:05 -0500 Subject: [PATCH 3/7] =?UTF-8?q?=F0=9F=90=9B=20fix:=20keep=20the=20review-f?= =?UTF-8?q?eedback=20reply=20style=20unchanged=20and=20accept=20the=20numb?= =?UTF-8?q?ered=20replies=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The brief's reply-style step is restored to its existing wording, so how an agent answers review feedback is not changed for every hive; only the no-probe and stop-on-refusal rules are added. The gate also accepts the documented POST pulls/{n}/comments/{id}/replies form and resolves the PR from the comment itself. Fixes #19096 Signed-off-by: Andy Anderson --- src/crux/proxy/review_thread.go | 6 +++--- src/crux/proxy/review_thread_test.go | 4 ++++ src/docs/github-write-surface.md | 2 +- src/docs/labels-and-control-signals/reference.md | 2 +- src/pkg/reviewfeedback/reviewfeedback.go | 2 +- src/pkg/reviewfeedback/reviewfeedback_test.go | 2 +- 6 files changed, 11 insertions(+), 7 deletions(-) diff --git a/src/crux/proxy/review_thread.go b/src/crux/proxy/review_thread.go index b955b61ad5..9366016454 100644 --- a/src/crux/proxy/review_thread.go +++ b/src/crux/proxy/review_thread.go @@ -22,7 +22,7 @@ import ( // needs two REST routes the rule table never had, so both fell through to // deny-by-default while the issue-comment route passed: // -// - POST /repos/{o}/{r}/pulls/comments/{id}/replies (reply in a thread) +// - POST /repos/{o}/{r}/pulls/[{n}/]comments/{id}/replies (reply in a thread) // - POST /repos/{o}/{r}/pulls/{n}/comments (PR review comment) // // They are allowed here, and only here, when the PR is one the hive's own @@ -62,7 +62,7 @@ const ( ) var ( - reviewReplyPathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/pulls/comments/(\d+)/replies$`) + reviewReplyPathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/pulls/(?:\d+/)?comments/(\d+)/replies$`) reviewPRCommentPathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/pulls/(\d+)/comments$`) ownCommentDeletePathRe = regexp.MustCompile(`^/repos/([^/]+/[^/]+)/(issues|pulls)/comments/(\d+)$`) ) @@ -76,7 +76,7 @@ var ( // order intact; they live here so rules.go stays inside its size ratchet. func init() { rules = append(rules, - ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/comments/\d+/replies$`), Method: http.MethodPost, MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, + ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/(?:\d+/)?comments/\d+/replies$`), Method: http.MethodPost, MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/pulls/\d+/comments$`), Method: http.MethodPost, MinMode: agent.ModeIssuesAndPRs, Capability: agent.AgentCapabilities.CanConverse}, ProxyRule{PathPattern: regexp.MustCompile(`^/repos/[^/]+/[^/]+/(?:issues|pulls)/comments/\d+$`), Method: http.MethodDelete, MinMode: agent.ModeIssuesOnly}, ) diff --git a/src/crux/proxy/review_thread_test.go b/src/crux/proxy/review_thread_test.go index ebeca77c54..99cd4662fd 100644 --- a/src/crux/proxy/review_thread_test.go +++ b/src/crux/proxy/review_thread_test.go @@ -114,6 +114,8 @@ func TestReviewThreadRefusal_Matrix(t *testing.T) { // Replies and PR review comments: the hive's PR, the agent that opened it. {"reply on hive PR by owning agent", rtOwner, "POST", replyPath, false, ""}, {"reply owner match is case-insensitive", "Quality", "POST", replyPath, false, ""}, + {"reply via the numbered documented path", rtOwner, "POST", "/repos/cncf/techdocs/pulls/424/comments/" + rtReplyID + "/replies", false, ""}, + {"numbered path resolves the PR from the comment, not the path", rtOwner, "POST", "/repos/cncf/techdocs/pulls/424/comments/777/replies", true, "was not opened by the hive's own agent"}, {"PR review comment by owning agent", rtOwner, "POST", "/repos/cncf/techdocs/pulls/424/comments", false, ""}, {"reply by another agent", "scanner", "POST", replyPath, true, "opened by agent quality, not by scanner"}, {"PR review comment by another agent", "scanner", "POST", "/repos/cncf/techdocs/pulls/424/comments", true, "not by scanner"}, @@ -304,6 +306,7 @@ func TestReviewThreadRules_ModeTable(t *testing.T) { {"reply at issues+prs", agent.ModeIssuesAndPRs, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/comments/1/replies", true}, {"reply at issues-only", agent.ModeIssuesOnly, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/comments/1/replies", false}, {"reply with converse", agent.ModeAdvisory, converse, "POST", "/repos/o/r/pulls/comments/1/replies", true}, + {"numbered reply at issues+prs", agent.ModeIssuesAndPRs, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/7/comments/1/replies", true}, {"pr comment at issues+prs", agent.ModeIssuesAndPRs, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/7/comments", true}, {"pr comment at advisory", agent.ModeAdvisory, agent.AgentCapabilities{}, "POST", "/repos/o/r/pulls/7/comments", false}, {"delete comment at issues-only", agent.ModeIssuesOnly, agent.AgentCapabilities{}, "DELETE", "/repos/o/r/issues/comments/1", true}, @@ -329,6 +332,7 @@ func TestReferenceRepoDecision_ReviewThreadRoutes(t *testing.T) { want referenceDecision }{ {"reply defers to the review-thread gate", both, "POST", "/repos/hivecommons/docs/pulls/comments/5/replies", referenceAllow}, + {"numbered reply defers to the gate", both, "POST", "/repos/hivecommons/docs/pulls/9/comments/5/replies", referenceAllow}, {"delete issue comment defers to the gate", both, "DELETE", "/repos/hivecommons/docs/issues/comments/5", referenceAllow}, {"delete review comment defers to the gate", both, "DELETE", "/repos/hivecommons/docs/pulls/comments/5", referenceAllow}, {"pr review comment keeps the own-item check", both, "POST", "/repos/hivecommons/docs/pulls/9/comments", referenceOwnItem}, diff --git a/src/docs/github-write-surface.md b/src/docs/github-write-surface.md index df7d752198..4109406384 100644 --- a/src/docs/github-write-surface.md +++ b/src/docs/github-write-surface.md @@ -285,7 +285,7 @@ agent to answer. The proxy lets it answer in place, and nothing wider | Route | Allowed when | | --- | --- | -| `POST /repos/{o}/{r}/pulls/comments/{id}/replies` | the comment's PR was opened by the hive's own agent (audit trail `agent_pr_created`, the sweep's ownership source) and the caller is the agent that opened it | +| `POST /repos/{o}/{r}/pulls/{n}/comments/{id}/replies` (also without `{n}`) | the comment's PR was opened by the hive's own agent (audit trail `agent_pr_created`, the sweep's ownership source) and the caller is the agent that opened it | | `POST /repos/{o}/{r}/pulls/{n}/comments` | the same: hive-opened PR, opening agent only | | `DELETE /repos/{o}/{r}/issues/comments/{id}`, `DELETE /repos/{o}/{r}/pulls/comments/{id}` | GitHub reports the comment was written by the hive's own identity (the App bot, or a reference repo's write login) and it is younger than `OwnCommentDeleteWindow` (15 minutes) | diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index 449b2e10e0..7818dc01bb 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -119,7 +119,7 @@ The labels the hive applies instead of `hold` ([#18468](https://github.com/hivec | `ready-for-review` | Hive's work is done; a maintainer reviews, then removes this label to let it merge. | The ACMM level gate (L3-L5, and cross-repo outreach at every level). | | `decision-needed` | Hive is blocked on a human decision; a maintainer decides (see hive's comment). | The #5117 self-authorization gate, the #9665 reporter-trust gate (with `needs-human`), the holdguard re-hold, and an owner-only delegated decision (with `needs-owner`). | -Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. Neither label stops the hive from answering review feedback: when a person leaves an inline comment, a review (`COMMENTED` or `CHANGES_REQUESTED`) or a comment addressed to the hive on a PR the hive's own agent opened, that agent is kicked to verify the claim and push a signed revision or reply with evidence, whether the PR is a draft, held, or in a repo the hive does not manage ([#19027](https://github.com/hivecommons/hive/issues/19027); `src/cmd/hive/review_feedback_wire.go`, `src/pkg/reviewfeedback/reviewfeedback.go`). A hold means do not merge, not do not respond. A burst of comments is coalesced into one kick after `HIVE_REVIEW_FEEDBACK_DEBOUNCE` (default 3m); comments that arrive while the agent works get their own follow-up kick; each PR is capped at `HIVE_REVIEW_FEEDBACK_WINDOW_CAP` kicks (default 12) per `HIVE_REVIEW_FEEDBACK_WINDOW` (default 24h), the cap posts a needs-human note, and a person's next comment resets it; `HIVE_REVIEW_FEEDBACK_MAX_ITEMS` (default 30) bounds one brief. Set `HIVE_REVIEW_FEEDBACK_RESPONSE=off` to disable the sweep. A comment that states a rule or a source of truth for future work is also captured into the hive's knowledge with its provenance, gated on the reviewer's association, and acknowledged on the PR ([#19046](https://github.com/hivecommons/hive/issues/19046); see [review-feedback-rules.md](../review-feedback-rules.md)). The kicked agent replies inside each thread with the replies endpoint, which the proxy allows only on the hive's own PR and only for the agent that opened it; it may delete its own comment within 15 minutes, never anyone else's, and is told never to post test or probe comments. If a reply is refused, the agent stops, the proxy keeps the drafted reply, and the sweep posts it in a needs-human note for a person to place ([#19096](https://github.com/hivecommons/hive/issues/19096); `src/crux/proxy/review_thread.go`, [GitHub write surface](../github-write-surface.md#review-thread-replies-on-the-hives-own-prs)). +Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. Neither label stops the hive from answering review feedback: when a person leaves an inline comment, a review (`COMMENTED` or `CHANGES_REQUESTED`) or a comment addressed to the hive on a PR the hive's own agent opened, that agent is kicked to verify the claim and push a signed revision or reply with evidence, whether the PR is a draft, held, or in a repo the hive does not manage ([#19027](https://github.com/hivecommons/hive/issues/19027); `src/cmd/hive/review_feedback_wire.go`, `src/pkg/reviewfeedback/reviewfeedback.go`). A hold means do not merge, not do not respond. A burst of comments is coalesced into one kick after `HIVE_REVIEW_FEEDBACK_DEBOUNCE` (default 3m); comments that arrive while the agent works get their own follow-up kick; each PR is capped at `HIVE_REVIEW_FEEDBACK_WINDOW_CAP` kicks (default 12) per `HIVE_REVIEW_FEEDBACK_WINDOW` (default 24h), the cap posts a needs-human note, and a person's next comment resets it; `HIVE_REVIEW_FEEDBACK_MAX_ITEMS` (default 30) bounds one brief. Set `HIVE_REVIEW_FEEDBACK_RESPONSE=off` to disable the sweep. A comment that states a rule or a source of truth for future work is also captured into the hive's knowledge with its provenance, gated on the reviewer's association, and acknowledged on the PR ([#19046](https://github.com/hivecommons/hive/issues/19046); see [review-feedback-rules.md](../review-feedback-rules.md)). Replies inside a review thread (the replies endpoint) are allowed by the proxy only on the hive's own PR and only for the agent that opened it; the agent may delete its own comment within 15 minutes, never anyone else's, and is told never to post test or probe comments. If a reply is refused, the agent stops, the proxy keeps the drafted reply, and the sweep posts it in a needs-human note for a person to place ([#19096](https://github.com/hivecommons/hive/issues/19096); `src/crux/proxy/review_thread.go`, [GitHub write surface](../github-write-surface.md#review-thread-replies-on-the-hives-own-prs)). **Migration.** On boot, Hive creates both labels (with their descriptions) in each active repository and swaps a literal `hold` for the matching gate label only when the newest `hold` event is a `labeled` by the Hive App **and** an App-authored gate notice is on the thread (level-hold notice → `ready-for-review`; reporter-trust, #5117, holdguard or owner-only decision notice → `decision-needed`). It adds the gate label before removing `hold` and leaves one `` comment. A `hold` a person applied (or re-applied) is never touched. Bounded to 50 items per repository per boot (`src/pkg/github/hive_gate_label_migration.go`). diff --git a/src/pkg/reviewfeedback/reviewfeedback.go b/src/pkg/reviewfeedback/reviewfeedback.go index 8760895748..9070e6a973 100644 --- a/src/pkg/reviewfeedback/reviewfeedback.go +++ b/src/pkg/reviewfeedback/reviewfeedback.go @@ -545,7 +545,7 @@ func BuildBriefWithRules(repo string, number int, headRef, writingGuide string, b.WriteString(" 2. In a thread with several messages, apply the LATEST position: a later reply can refine or change what the first comment meant (a different target, a different number). Reply to the latest message.\n") b.WriteString(" 3. If the reviewer is right: fix it on the SAME branch (gh pr checkout, edit, git commit -s, git push). No replacement PR.\n") b.WriteString(" 4. If the reviewer is wrong or it is a judgment call: reply politely with the evidence. Never argue to defend a score or to please the reviewer; accuracy is the only goal.\n") - b.WriteString(" 5. Reply inside each thread with the replies endpoint: gh api -X POST repos/OWNER/REPO/pulls/comments/ID/replies -f body=... where ID is the newest message in the thread. Answer review summaries and conversation comments with one PR comment. Each reply says what you verified, what you changed and in which commit, and what you left unchanged and why.\n") + b.WriteString(" 5. Reply inside each thread (gh api repos/OWNER/REPO/pulls/N/comments/ID/replies), or on the PR for review and conversation comments. Each reply says what you verified, what you changed and in which commit, and what you left unchanged and why.\n") if len(rules) == 0 { b.WriteString(" 6. Rules, not only corrections. If a comment states a rule or a source of truth for future assessments (for example which file is authoritative for ownership), record it durably: write a knowledge fact in the hive's own knowledge store with `hivectl knowledge create --file fact.yaml` (title, body, tags, and the PR comment URL as the source), then say so in your reply. If the right home for the rule is another project's repo (for example its criteria files), do NOT write there: propose the exact text in your reply and say a person needs to place it. If hivectl cannot write, say so in the reply instead of dropping the rule.\n") } else { diff --git a/src/pkg/reviewfeedback/reviewfeedback_test.go b/src/pkg/reviewfeedback/reviewfeedback_test.go index 3752bd3722..6069756298 100644 --- a/src/pkg/reviewfeedback/reviewfeedback_test.go +++ b/src/pkg/reviewfeedback/reviewfeedback_test.go @@ -429,7 +429,7 @@ func TestStorePendingReplyPersistsAndMerges(t *testing.T) { func TestBuildBrief_RepliesEndpointAndNoProbeComments(t *testing.T) { brief := BuildBrief("o/r", 1, "", "", []github.FeedbackItem{item("inline:1")}) - for _, want := range []string{"pulls/comments/ID/replies", "Never post a test, probe or placeholder comment", "If a reply or any other write is refused", "STOP"} { + for _, want := range []string{"comments/ID/replies", "Never post a test, probe or placeholder comment", "If a reply or any other write is refused", "STOP"} { if !strings.Contains(brief, want) { t.Errorf("brief missing %q", want) } From fba7857e784fb6554acfdaffb51c34b98ad13c4d Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 15:58:07 -0500 Subject: [PATCH 4/7] =?UTF-8?q?=F0=9F=90=9B=20test:=20drain=20the=20forwar?= =?UTF-8?q?ded=20body=20in=20the=20review-thread=20MITM=20test=20so=20net.?= =?UTF-8?q?Pipe=20cannot=20deadlock?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #19096 Signed-off-by: Andy Anderson --- src/crux/proxy/review_thread_test.go | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/src/crux/proxy/review_thread_test.go b/src/crux/proxy/review_thread_test.go index 99cd4662fd..09d3ddd1d0 100644 --- a/src/crux/proxy/review_thread_test.go +++ b/src/crux/proxy/review_thread_test.go @@ -384,7 +384,8 @@ func TestProxyHTTP_ReviewThreadGate(t *testing.T) { fmt.Fprintf(clientConn, "POST /repos/cncf/techdocs/pulls/424/comments HTTP/1.1\r\nHost: api.github.com\r\nContent-Type: application/json\r\nContent-Length: %d\r\n\r\n%s", len(body), body) }() if tc.wantCode == http.StatusCreated { - go answerOnce(upstreamConn, http.StatusCreated) + go answerDrained(upstreamConn, http.StatusCreated) + _ = clientConn.SetReadDeadline(time.Now().Add(10 * time.Second)) resp, err := http.ReadResponse(bufio.NewReader(clientConn), nil) if err != nil { t.Fatalf("read response: %v", err) @@ -407,3 +408,20 @@ func TestProxyHTTP_ReviewThreadGate(t *testing.T) { }) } } + +// answerDrained is answerOnce for a request with a body: over net.Pipe the +// proxy's body write blocks until it is read, so the body is drained before +// the response is written. +func answerDrained(upstream net.Conn, status int) { + req, err := http.ReadRequest(bufio.NewReader(upstream)) + if err != nil { + return + } + _, _ = io.Copy(io.Discard, req.Body) + resp := &http.Response{ + StatusCode: status, Proto: "HTTP/1.1", ProtoMajor: 1, ProtoMinor: 1, + Header: make(http.Header), Body: http.NoBody, Request: req, + } + _ = resp.Write(upstream) + _ = upstream.Close() +} From b9aa19c1b5286b87f38087a457aae3f92099340f Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 20:24:20 -0500 Subject: [PATCH 5/7] =?UTF-8?q?=F0=9F=90=9B=20fix:=20close=20the=20brief?= =?UTF-8?q?=20test=20block=20after=20the=20rebase=20onto=20v5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/pkg/reviewfeedback/reviewfeedback_test.go | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pkg/reviewfeedback/reviewfeedback_test.go b/src/pkg/reviewfeedback/reviewfeedback_test.go index 6069756298..4cae0c2089 100644 --- a/src/pkg/reviewfeedback/reviewfeedback_test.go +++ b/src/pkg/reviewfeedback/reviewfeedback_test.go @@ -433,6 +433,5 @@ func TestBuildBrief_RepliesEndpointAndNoProbeComments(t *testing.T) { if !strings.Contains(brief, want) { t.Errorf("brief missing %q", want) } - } } } From e6bdfdfc6bd6af67fa170a9b1923096b6fbe9fd1 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 20:52:10 -0500 Subject: [PATCH 6/7] =?UTF-8?q?=F0=9F=90=9B=20fix:=20limit=20own-comment?= =?UTF-8?q?=20delete=20to=20a=20PR=20the=20calling=20agent=20opened?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every agent posts as the same App bot, so the author and age checks alone let any agent delete another agent's or a reviewer's comment. The delete gate now resolves the comment's PR from its own pull_request_url or issue_url and refuses unless the caller opened it, the same OwnPR check the reply path uses. Lookup failures refuse. Signed-off-by: Andy Anderson --- src/crux/proxy/review_thread.go | 63 +++++++++--- src/crux/proxy/review_thread_test.go | 96 ++++++++++++++++--- src/docs/github-write-surface.md | 6 +- .../labels-and-control-signals/reference.md | 2 +- 4 files changed, 139 insertions(+), 28 deletions(-) diff --git a/src/crux/proxy/review_thread.go b/src/crux/proxy/review_thread.go index 9366016454..49593c4e07 100644 --- a/src/crux/proxy/review_thread.go +++ b/src/crux/proxy/review_thread.go @@ -33,9 +33,17 @@ import ( // // An agent may also retract its own mistake: DELETE of an issue comment or a // review comment is allowed only when GitHub says the comment was written by -// the hive's own identity and it is younger than OwnCommentDeleteWindow. -// Anyone else's comment, and any older one, stays refused. A lookup that -// fails refuses (fail closed) and says so. +// the hive's own identity, it is younger than OwnCommentDeleteWindow, and it +// sits on a PR the calling agent opened. Every agent posts as the same App +// bot, so the author check alone cannot tell one agent's comment from +// another's; the PR-owner check is what keeps an agent from deleting another +// agent's or a reviewer's comment elsewhere (maintainer decision on #19102). +// The PR is read from the comment's own pull_request_url (review comment) or +// issue_url (issue comment) via the API, never from the request path, and is +// checked against OwnPR exactly as the reply path does. Anyone else's +// comment, any older one, one on a PR another agent opened, and one whose PR +// cannot be resolved stays refused. A lookup that fails refuses (fail +// closed) and says so. // DenyReasonReviewThread is the 403 reason code for a refused review-thread // reply, PR review comment or comment delete (see denial_message.go). @@ -70,7 +78,7 @@ var ( // The mode-table rules for the guarded routes. They only say WHICH modes may: // the review-thread gate runs first and refuses the reply routes unless the PR // is the hive's own and the caller opened it, and a delete unless the comment -// is the hive's own and recent. Replies and PR review comments sit at the tier +// is the hive's own, recent and on the caller's own PR. Replies and PR review comments sit at the tier // of a review (ISSUES_AND_PRS or converse); a delete at ISSUES_ONLY. No other // rule matches these (method, path) pairs, so appending keeps first-match-wins // order intact; they live here so rules.go stays inside its size ratchet. @@ -177,7 +185,7 @@ func (g ReviewThreadGuard) now() time.Time { // stop instead of probing other routes: a probe comment on a person's review // is worse than an unanswered thread. func reviewThreadRefusalText(why string) string { - return "review-thread write refused: " + why + ". Replies inside review threads and PR review comments are allowed only on a PR the hive's own agent opened, and only for the agent that opened it; deleting a comment is allowed only for the hive's own comment within " + OwnCommentDeleteWindow.String() + " of posting. Do NOT retry, do NOT post the reply as an issue comment instead, and NEVER post a test or probe comment. Stop here: the hive's review-feedback sweep hands your drafted reply to a person." + return "review-thread write refused: " + why + ". Replies inside review threads and PR review comments are allowed only on a PR the hive's own agent opened, and only for the agent that opened it; deleting a comment is allowed only for the hive's own comment within " + OwnCommentDeleteWindow.String() + " of posting, and only on a PR the calling agent opened. Do NOT retry, do NOT post the reply as an issue comment instead, and NEVER post a test or probe comment. Stop here: the hive's review-feedback sweep hands your drafted reply to a person." } // reviewThreadRefusal is the per-request gate the MITM loop calls for @@ -207,12 +215,19 @@ func (p *GitHubProxy) reviewThreadRefusal(req *http.Request, agentName string) ( } number = n } - owner, owned := g.OwnPR(w.repo, number) + return ownPRCallerRefusal(g, w.repo, number, agentName) +} + +// ownPRCallerRefusal refuses unless repo#number is a PR the hive's own agent +// opened and agentName is that agent. Replies, PR review comments and +// deletes all share it. +func ownPRCallerRefusal(g ReviewThreadGuard, repo string, number int, agentName string) (string, bool) { + owner, owned := g.OwnPR(repo, number) if !owned { - return reviewThreadRefusalText(fmt.Sprintf("%s#%d was not opened by the hive's own agent", w.repo, number)), true + return reviewThreadRefusalText(fmt.Sprintf("%s#%d was not opened by the hive's own agent", repo, number)), true } if !strings.EqualFold(owner, agentName) { - return reviewThreadRefusalText(fmt.Sprintf("%s#%d was opened by agent %s, not by %s", w.repo, number, owner, agentName)), true + return reviewThreadRefusalText(fmt.Sprintf("%s#%d was opened by agent %s, not by %s", repo, number, owner, agentName)), true } return "", false } @@ -271,7 +286,8 @@ func peekReviewDraft(req *http.Request) (body, inReplyTo string) { return payload.Body, strings.Trim(string(payload.InReplyTo), `"`) } -// ownCommentDeleteRefusal allows DELETE only of the hive's own recent comment. +// ownCommentDeleteRefusal allows DELETE only of the hive's own recent comment +// on a PR the calling agent opened. func (p *GitHubProxy) ownCommentDeleteRefusal(req *http.Request, agentName string, w reviewThreadWrite, g ReviewThreadGuard) (string, bool) { meta, err := p.reviewCommentMeta(req, agentName, w.repo, w.commentSurface, w.commentID) if err != nil { @@ -295,7 +311,11 @@ func (p *GitHubProxy) ownCommentDeleteRefusal(req *http.Request, agentName strin if age > OwnCommentDeleteWindow { return reviewThreadRefusalText(fmt.Sprintf("comment %s is %s old, past the %s retract window", w.commentID, age.Round(time.Second), OwnCommentDeleteWindow)), true } - return "", false + number, err := commentPRNumber(meta, w.commentSurface) + if err != nil { + return reviewThreadRefusalText(fmt.Sprintf("could not resolve which PR comment %s belongs to (%v)", w.commentID, err)), true + } + return ownPRCallerRefusal(g, w.repo, number, agentName) } // hiveLoginsFor is the hive's identity on repo: the guard's logins plus the @@ -318,6 +338,9 @@ type reviewCommentMetadata struct { } `json:"user"` CreatedAt time.Time `json:"created_at"` PullRequestURL string `json:"pull_request_url"` + // IssueURL is set on an issue comment; on a PR conversation comment it + // points at the PR's issue number. + IssueURL string `json:"issue_url"` } // reviewCommentMeta GETs /repos/{repo}/{issues|pulls}/comments/{id}. @@ -342,13 +365,25 @@ func (p *GitHubProxy) reviewCommentPR(req *http.Request, agentName string, w rev if err != nil { return 0, err } - i := strings.LastIndex(meta.PullRequestURL, "/pulls/") + return commentPRNumber(meta, "pulls") +} + +// commentPRNumber reads the PR (or issue) number a comment belongs to from +// the comment GitHub returned: pull_request_url for a review comment +// ("pulls"), issue_url for an issue comment ("issues"). Never the request +// path. +func commentPRNumber(meta reviewCommentMetadata, surface string) (int, error) { + field, url, seg := "pull_request_url", meta.PullRequestURL, "/pulls/" + if surface == "issues" { + field, url, seg = "issue_url", meta.IssueURL, "/issues/" + } + i := strings.LastIndex(url, seg) if i < 0 { - return 0, fmt.Errorf("comment carries no pull_request_url") + return 0, fmt.Errorf("comment carries no %s", field) } - n, err := strconv.Atoi(meta.PullRequestURL[i+len("/pulls/"):]) + n, err := strconv.Atoi(url[i+len(seg):]) if err != nil || n <= 0 { - return 0, fmt.Errorf("unreadable pull_request_url %q", meta.PullRequestURL) + return 0, fmt.Errorf("unreadable %s %q", field, url) } return n, nil } diff --git a/src/crux/proxy/review_thread_test.go b/src/crux/proxy/review_thread_test.go index 09d3ddd1d0..1c4e2efc1d 100644 --- a/src/crux/proxy/review_thread_test.go +++ b/src/crux/proxy/review_thread_test.go @@ -24,6 +24,9 @@ const ( rtReplyID = "4616203214" rtOtherPR = 99 rtCommentA = "6988449875" + // rtPeerPR is a hive PR another agent (rtPeer) opened. + rtPeerPR = 500 + rtPeer = "scanner" ) // rtFixture is the fake GitHub the gate's own GETs read. @@ -51,19 +54,29 @@ func (f *rtFixture) lookup(url, token string) ([]byte, error) { func newRTFixture(now time.Time) *rtFixture { at := func(d time.Duration) string { return now.Add(-d).UTC().Format(time.RFC3339) } + issueURL := func(n int) string { return fmt.Sprintf("https://api.github.com/repos/cncf/techdocs/issues/%d", n) } + pullURL := func(n int) string { return fmt.Sprintf("https://api.github.com/repos/cncf/techdocs/pulls/%d", n) } return &rtFixture{now: now, comments: map[string]string{ // A person's review comment on the hive's PR, and one on another PR. "/repos/cncf/techdocs/pulls/comments/" + rtReplyID: fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q,"pull_request_url":"https://api.github.com/repos/cncf/techdocs/pulls/%d"}`, at(time.Hour), rtPR), "/repos/cncf/techdocs/pulls/comments/777": fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q,"pull_request_url":"https://api.github.com/repos/cncf/techdocs/pulls/%d"}`, at(time.Hour), rtOtherPR), "/repos/cncf/techdocs/pulls/comments/778": `{"user":{"login":"nate"},"created_at":"2026-01-01T00:00:00Z"}`, - // The hive's own probe comment, two minutes old. - "/repos/cncf/techdocs/issues/comments/" + rtCommentA: fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(2*time.Minute)), - // The hive's own comment, but an hour old. - "/repos/cncf/techdocs/issues/comments/100": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(time.Hour)), - // A person's comment, a minute old. - "/repos/cncf/techdocs/issues/comments/101": fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q}`, at(time.Minute)), - // The hive's own review comment, a minute old. - "/repos/cncf/techdocs/pulls/comments/102": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(time.Minute)), + // The hive's own probe comment on rtOwner's PR, two minutes old. + "/repos/cncf/techdocs/issues/comments/" + rtCommentA: fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"issue_url":%q}`, rtHiveBot, at(2*time.Minute), issueURL(rtPR)), + // The hive's own comment on rtOwner's PR, but an hour old. + "/repos/cncf/techdocs/issues/comments/100": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"issue_url":%q}`, rtHiveBot, at(time.Hour), issueURL(rtPR)), + // A person's comment on rtOwner's PR, a minute old. + "/repos/cncf/techdocs/issues/comments/101": fmt.Sprintf(`{"user":{"login":"nate"},"created_at":%q,"issue_url":%q}`, at(time.Minute), issueURL(rtPR)), + // The hive's own review comment on rtOwner's PR, a minute old. + "/repos/cncf/techdocs/pulls/comments/102": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"pull_request_url":%q}`, rtHiveBot, at(time.Minute), pullURL(rtPR)), + // Hive-bot comments, a minute old, on a PR another agent opened. + "/repos/cncf/techdocs/issues/comments/105": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"issue_url":%q}`, rtHiveBot, at(time.Minute), issueURL(rtPeerPR)), + "/repos/cncf/techdocs/pulls/comments/106": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"pull_request_url":%q}`, rtHiveBot, at(time.Minute), pullURL(rtPeerPR)), + // A hive-bot comment, a minute old, on a PR the hive did not open. + "/repos/cncf/techdocs/issues/comments/107": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"issue_url":%q}`, rtHiveBot, at(time.Minute), issueURL(rtOtherPR)), + // A hive-bot comment, a minute old, whose PR GitHub does not say. + "/repos/cncf/techdocs/issues/comments/108": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(time.Minute)), + "/repos/cncf/techdocs/pulls/comments/109": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"pull_request_url":"https://api.github.com/repos/cncf/techdocs/pulls/x"}`, rtHiveBot, at(time.Minute)), // The hive's comment dated in the future (clock trouble): unknown. "/repos/cncf/techdocs/issues/comments/103": fmt.Sprintf(`{"user":{"login":%q},"created_at":%q}`, rtHiveBot, at(-time.Hour)), // No author at all. @@ -75,6 +88,9 @@ func rtOwnPR(repo string, number int) (string, bool) { if strings.EqualFold(repo, rtRepo) && number == rtPR { return rtOwner, true } + if strings.EqualFold(repo, rtRepo) && number == rtPeerPR { + return rtPeer, true + } return "", false } @@ -125,9 +141,16 @@ func TestReviewThreadRefusal_Matrix(t *testing.T) { {"reply whose comment cannot be found", rtOwner, "POST", "/repos/cncf/techdocs/pulls/comments/5/replies", true, "could not resolve"}, {"reply whose comment has no PR url", rtOwner, "POST", "/repos/cncf/techdocs/pulls/comments/778/replies", true, "no pull_request_url"}, {"unidentified caller", "", "POST", replyPath, true, "could not be identified"}, - // Deletes: the hive's own comment inside the window only. - {"delete own recent issue comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/" + rtCommentA, false, ""}, - {"delete own recent review comment", "scanner", "DELETE", "/repos/cncf/techdocs/pulls/comments/102", false, ""}, + // Deletes: the hive's own comment, inside the window, on the caller's own PR only. + {"delete own recent issue comment on own PR", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/" + rtCommentA, false, ""}, + {"delete own recent review comment on own PR", rtOwner, "DELETE", "/repos/cncf/techdocs/pulls/comments/102", false, ""}, + {"delete hive-bot issue comment on own PR by another agent", rtPeer, "DELETE", "/repos/cncf/techdocs/issues/comments/" + rtCommentA, true, "opened by agent quality, not by scanner"}, + {"delete hive-bot review comment on own PR by another agent", rtPeer, "DELETE", "/repos/cncf/techdocs/pulls/comments/102", true, "opened by agent quality, not by scanner"}, + {"delete hive-bot issue comment on a PR another agent opened", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/105", true, "opened by agent scanner, not by quality"}, + {"delete hive-bot review comment on a PR another agent opened", rtOwner, "DELETE", "/repos/cncf/techdocs/pulls/comments/106", true, "opened by agent scanner, not by quality"}, + {"delete hive-bot comment on a PR the hive did not open", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/107", true, "was not opened by the hive's own agent"}, + {"delete hive-bot comment with no issue_url", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/108", true, "no issue_url"}, + {"delete hive-bot review comment with unreadable pull_request_url", rtOwner, "DELETE", "/repos/cncf/techdocs/pulls/comments/109", true, "unreadable pull_request_url"}, {"delete own old comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/100", true, "past the 15m0s retract window"}, {"delete someone else's comment", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/101", true, "written by nate, not by the hive"}, {"delete comment dated in the future", rtOwner, "DELETE", "/repos/cncf/techdocs/issues/comments/103", true, "no usable creation time"}, @@ -202,9 +225,58 @@ func TestReviewThreadRefusal_LookupFailureFailsClosed(t *testing.T) { } } +// TestOwnCommentDelete_ScopedToCallersOwnPR asserts the delete invariant +// (maintainer decision on #19102): a hive-bot comment may be deleted only by +// the agent that opened the PR it sits on, only inside +// OwnCommentDeleteWindow, and every lookup failure refuses. +func TestOwnCommentDelete_ScopedToCallersOwnPR(t *testing.T) { + const ownPath = "/repos/cncf/techdocs/issues/comments/" + rtCommentA + t.Run("lookup failure refuses every caller", func(t *testing.T) { + f := newRTFixture(time.Now()) + f.failAll = true + p := newRTProxy(t, f, nil) + for _, caller := range []string{rtOwner, rtPeer} { + for _, path := range []string{ownPath, "/repos/cncf/techdocs/pulls/comments/102"} { + reason, refused := p.reviewThreadRefusal(rtReq("DELETE", path, ""), caller) + if !refused || !strings.Contains(reason, "could not confirm") { + t.Fatalf("%s DELETE %s on lookup failure: refused=%v reason=%q", caller, path, refused, reason) + } + } + } + }) + t.Run("ownership read from the comment, not from the guard's first PR", func(t *testing.T) { + f := newRTFixture(time.Now()) + p := newRTProxy(t, f, nil) + if _, refused := p.reviewThreadRefusal(rtReq("DELETE", "/repos/cncf/techdocs/issues/comments/105", ""), rtPeer); refused { + t.Fatal("the agent that opened the PR the comment sits on may retract it") + } + if _, refused := p.reviewThreadRefusal(rtReq("DELETE", "/repos/cncf/techdocs/issues/comments/105", ""), rtOwner); !refused { + t.Fatal("a hive-bot comment on another agent's PR must be refused") + } + }) + t.Run("age limit is OwnCommentDeleteWindow", func(t *testing.T) { + const margin = time.Second + for _, tc := range []struct { + age time.Duration + wantRefuse bool + }{ + {OwnCommentDeleteWindow - margin, false}, + {OwnCommentDeleteWindow + margin, true}, + } { + f := newRTFixture(time.Now()) + f.comments[ownPath] = fmt.Sprintf(`{"user":{"login":%q},"created_at":%q,"issue_url":"https://api.github.com/repos/cncf/techdocs/issues/%d"}`, rtHiveBot, f.now.Add(-tc.age).UTC().Format(time.RFC3339Nano), rtPR) + p := newRTProxy(t, f, nil) + reason, refused := p.reviewThreadRefusal(rtReq("DELETE", ownPath, ""), rtOwner) + if refused != tc.wantRefuse { + t.Fatalf("age %s: refused=%v want %v (%q)", tc.age, refused, tc.wantRefuse, reason) + } + } + }) +} + func TestReviewThreadRefusal_ReferenceRepoLoginCountsAsHive(t *testing.T) { f := newRTFixture(time.Now()) - f.comments["/repos/cncf/techdocs/issues/comments/200"] = fmt.Sprintf(`{"user":{"login":"hive-owner"},"created_at":%q}`, f.now.Add(-time.Minute).UTC().Format(time.RFC3339)) + f.comments["/repos/cncf/techdocs/issues/comments/200"] = fmt.Sprintf(`{"user":{"login":"hive-owner"},"created_at":%q,"issue_url":"https://api.github.com/repos/cncf/techdocs/issues/%d"}`, f.now.Add(-time.Minute).UTC().Format(time.RFC3339), rtPR) p := newRTProxy(t, f, nil) pol := ReferenceRepoPolicy{Repo: rtRepo, Issues: true, PRs: true, Login: "hive-owner", Token: func() (string, bool) { return "ref-tok", true }} p.SetReferenceRepos([]ReferenceRepoPolicy{pol}) diff --git a/src/docs/github-write-surface.md b/src/docs/github-write-surface.md index 4109406384..adbe43eca8 100644 --- a/src/docs/github-write-surface.md +++ b/src/docs/github-write-surface.md @@ -287,8 +287,12 @@ agent to answer. The proxy lets it answer in place, and nothing wider | --- | --- | | `POST /repos/{o}/{r}/pulls/{n}/comments/{id}/replies` (also without `{n}`) | the comment's PR was opened by the hive's own agent (audit trail `agent_pr_created`, the sweep's ownership source) and the caller is the agent that opened it | | `POST /repos/{o}/{r}/pulls/{n}/comments` | the same: hive-opened PR, opening agent only | -| `DELETE /repos/{o}/{r}/issues/comments/{id}`, `DELETE /repos/{o}/{r}/pulls/comments/{id}` | GitHub reports the comment was written by the hive's own identity (the App bot, or a reference repo's write login) and it is younger than `OwnCommentDeleteWindow` (15 minutes) | +| `DELETE /repos/{o}/{r}/issues/comments/{id}`, `DELETE /repos/{o}/{r}/pulls/comments/{id}` | GitHub reports the comment was written by the hive's own identity (the App bot, or a reference repo's write login), it is younger than `OwnCommentDeleteWindow` (15 minutes), and it sits on a PR the calling agent opened (read from the comment's own `pull_request_url` or `issue_url`, never the request path, and checked against the audit trail as for replies) | +Every agent posts as the same App bot, so the author check alone would let one +agent delete another agent's or a reviewer's comment; the PR-owner check is +what limits a delete to the caller's own PR (maintainer decision on +[#19102](https://github.com/hivecommons/hive/pull/19102)). Any other PR, any other agent, anyone else's comment, an older comment, and any lookup that fails are refused with the `review_thread` reason, and the agent is told to stop rather than probe another route. The mode tier still diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index 7818dc01bb..562c156425 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -119,7 +119,7 @@ The labels the hive applies instead of `hold` ([#18468](https://github.com/hivec | `ready-for-review` | Hive's work is done; a maintainer reviews, then removes this label to let it merge. | The ACMM level gate (L3-L5, and cross-repo outreach at every level). | | `decision-needed` | Hive is blocked on a human decision; a maintainer decides (see hive's comment). | The #5117 self-authorization gate, the #9665 reporter-trust gate (with `needs-human`), the holdguard re-hold, and an owner-only delegated decision (with `needs-owner`). | -Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. Neither label stops the hive from answering review feedback: when a person leaves an inline comment, a review (`COMMENTED` or `CHANGES_REQUESTED`) or a comment addressed to the hive on a PR the hive's own agent opened, that agent is kicked to verify the claim and push a signed revision or reply with evidence, whether the PR is a draft, held, or in a repo the hive does not manage ([#19027](https://github.com/hivecommons/hive/issues/19027); `src/cmd/hive/review_feedback_wire.go`, `src/pkg/reviewfeedback/reviewfeedback.go`). A hold means do not merge, not do not respond. A burst of comments is coalesced into one kick after `HIVE_REVIEW_FEEDBACK_DEBOUNCE` (default 3m); comments that arrive while the agent works get their own follow-up kick; each PR is capped at `HIVE_REVIEW_FEEDBACK_WINDOW_CAP` kicks (default 12) per `HIVE_REVIEW_FEEDBACK_WINDOW` (default 24h), the cap posts a needs-human note, and a person's next comment resets it; `HIVE_REVIEW_FEEDBACK_MAX_ITEMS` (default 30) bounds one brief. Set `HIVE_REVIEW_FEEDBACK_RESPONSE=off` to disable the sweep. A comment that states a rule or a source of truth for future work is also captured into the hive's knowledge with its provenance, gated on the reviewer's association, and acknowledged on the PR ([#19046](https://github.com/hivecommons/hive/issues/19046); see [review-feedback-rules.md](../review-feedback-rules.md)). Replies inside a review thread (the replies endpoint) are allowed by the proxy only on the hive's own PR and only for the agent that opened it; the agent may delete its own comment within 15 minutes, never anyone else's, and is told never to post test or probe comments. If a reply is refused, the agent stops, the proxy keeps the drafted reply, and the sweep posts it in a needs-human note for a person to place ([#19096](https://github.com/hivecommons/hive/issues/19096); `src/crux/proxy/review_thread.go`, [GitHub write surface](../github-write-surface.md#review-thread-replies-on-the-hives-own-prs)). +Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. Neither label stops the hive from answering review feedback: when a person leaves an inline comment, a review (`COMMENTED` or `CHANGES_REQUESTED`) or a comment addressed to the hive on a PR the hive's own agent opened, that agent is kicked to verify the claim and push a signed revision or reply with evidence, whether the PR is a draft, held, or in a repo the hive does not manage ([#19027](https://github.com/hivecommons/hive/issues/19027); `src/cmd/hive/review_feedback_wire.go`, `src/pkg/reviewfeedback/reviewfeedback.go`). A hold means do not merge, not do not respond. A burst of comments is coalesced into one kick after `HIVE_REVIEW_FEEDBACK_DEBOUNCE` (default 3m); comments that arrive while the agent works get their own follow-up kick; each PR is capped at `HIVE_REVIEW_FEEDBACK_WINDOW_CAP` kicks (default 12) per `HIVE_REVIEW_FEEDBACK_WINDOW` (default 24h), the cap posts a needs-human note, and a person's next comment resets it; `HIVE_REVIEW_FEEDBACK_MAX_ITEMS` (default 30) bounds one brief. Set `HIVE_REVIEW_FEEDBACK_RESPONSE=off` to disable the sweep. A comment that states a rule or a source of truth for future work is also captured into the hive's knowledge with its provenance, gated on the reviewer's association, and acknowledged on the PR ([#19046](https://github.com/hivecommons/hive/issues/19046); see [review-feedback-rules.md](../review-feedback-rules.md)). Replies inside a review thread (the replies endpoint) are allowed by the proxy only on the hive's own PR and only for the agent that opened it; the agent may delete a hive comment within 15 minutes only on a PR it opened, never anyone else's or one on another agent's PR, and is told never to post test or probe comments. If a reply is refused, the agent stops, the proxy keeps the drafted reply, and the sweep posts it in a needs-human note for a person to place ([#19096](https://github.com/hivecommons/hive/issues/19096); `src/crux/proxy/review_thread.go`, [GitHub write surface](../github-write-surface.md#review-thread-replies-on-the-hives-own-prs)). **Migration.** On boot, Hive creates both labels (with their descriptions) in each active repository and swaps a literal `hold` for the matching gate label only when the newest `hold` event is a `labeled` by the Hive App **and** an App-authored gate notice is on the thread (level-hold notice → `ready-for-review`; reporter-trust, #5117, holdguard or owner-only decision notice → `decision-needed`). It adds the gate label before removing `hold` and leaves one `` comment. A `hold` a person applied (or re-applied) is never touched. Bounded to 50 items per repository per boot (`src/pkg/github/hive_gate_label_migration.go`). From e20206c63230793af5f237de610efc1ec19b01c9 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 20:52:23 -0500 Subject: [PATCH 7/7] =?UTF-8?q?=F0=9F=93=9D=20docs:=20changelog=20scopes?= =?UTF-8?q?=20own-comment=20delete=20to=20the=20caller's=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- changelog.d/fixed-19096-review-thread-replies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/fixed-19096-review-thread-replies.md b/changelog.d/fixed-19096-review-thread-replies.md index a2a70ecd4e..e76f78d024 100644 --- a/changelog.d/fixed-19096-review-thread-replies.md +++ b/changelog.d/fixed-19096-review-thread-replies.md @@ -1 +1 @@ -- Let the agent that opened a PR reply inside its review threads (`pulls/comments/{id}/replies`, `pulls/{n}/comments`) and retract the hive's own comment within 15 minutes; every other PR, agent and comment stays refused, the review-feedback brief forbids probe comments, and a refused reply is posted in the sweep's needs-human note for a person (#19096). +- Let the agent that opened a PR reply inside its review threads (`pulls/comments/{id}/replies`, `pulls/{n}/comments`) and retract a hive comment within 15 minutes on a PR that agent opened; every other PR, agent and comment stays refused, the review-feedback brief forbids probe comments, and a refused reply is posted in the sweep's needs-human note for a person (#19096).