Skip to content

✨ feat(adminmcp): read and act on the Activity monitor; writes run as the verified caller - #16884

Merged
hivecommons-hive[bot] merged 8 commits into
hivecommons:v6from
Danathar:feat/adminmcp-stage-tracker
Nov 6, 2026
Merged

hivecommons-hive[bot] merged 8 commits into
hivecommons:v6from
Danathar:feat/adminmcp-stage-tracker

Conversation

@Danathar

@Danathar Danathar commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Executive summary

The admin MCP can now read the Activity monitor and press its buttons.

  • Read: stage_tracker_read returns the board the Activity monitor draws (GET /api/stage-tracker): each item's stage, what it waits on, its decision question and options, linked PRs and issues, blocker, hold and needs-human state, plus a count per stage. It has the monitor's filters, including its search box, where a number matches the item or a linked item. delegated_decision_status reads the outcome of a "Let hive decide".
  • Write: the monitor's row actions are new write operations under the existing preview-and-confirm contract: Re-evaluate now, Accept triage, Mark needs-human, the three blocker actions, the Decide menu and Let hive decide. Hold already existed.
  • Never merges: "Merge now" and "Approve and let hive merge" are refused, the same as queue-automerge ([RFC] [v6] Operator-facing admin MCP: administer a hive by conversation #8697). A delegated decision sent through admin MCP carries a new no_merge flag, so a merger's delegated approval cannot queue an auto-merge either.
  • Writes run as the caller: before this, a confirmed write on the HTTP endpoint re-authenticated with the dashboard token alone, so a caller who came in through the hub or a dashboard session could not write at all, and every write was recorded under the configured owner. Now the write runs as the identity the hive itself verified on the request. A confirmation is bound to whoever previewed it.

What

Tool / operation Activity monitor equivalent Endpoint
stage_tracker_read the board, filters and search box GET /api/stage-tracker
delegated_decision_status the "Let hive decide" result toast GET …/items/{n}/decide-delegated
repository.rescan Re-evaluate now POST /api/repos/rescan
repository.item_accept_triage Accept triage POST …/items/{n}/accept-triage
repository.item_needs_human Mark needs-human… POST /api/review/pipeline/{o}/{r}/{n}/send-to-human
repository.item_blocker_recheck / _handoff / _close_partial blocker menu POST …/items/{n}/blocker/{recheck,handoff,close-partial}
repository.item_decision Decide… POST …/items/{n}/decision
repository.item_delegate Let hive decide (and "— all N PRs") POST …/items/{n}/decide-delegated with no_merge
repository.item_hold (existing) Hold / Release hold POST …/items/{n}/hold

repository.item_decision takes approve, direction, close-superseded, close-wontfix, close-read, close-issue, adopt, adopt-now, re-author and reroute. merge-now and queue-merge are refused before any request, and the exclusion catalogue records why.

Why

  • An assistant could see only band counts (issues_by_band, prs_by_band), not what the monitor shows: how long an item has sat, what it waits on, how issues and PRs link, and the decision options.
  • On a hub-managed hive, the admin MCP is reached through the hub proxy. adminMCPWritesUnavailableReason refused every write for such a caller ("admitted another way … a confirmed write would be refused with 401"), so no write tool worked there at all.
  • Decide, Let hive decide, the blocker actions and needs-human record who decided. Through the token path they would have been recorded under the configured owner, not the person deciding.

How

  • pkg/adminmcp/tools_stage_tracker.go:

    • StageTrackerReadResult filters, trims (view=summary keeps the row's fields; full keeps all) and pages. Stage counts always cover the whole board.
    • The q filter follows tracker-filter.js stageTrackerMatches.
    • Each item op sends exactly what stageTrackerActionRequest in tracker-actions.js sends.
    • Item previews read the item off the board through the provider. The preview then shows its kind, stage, reason and decision question; supplies the PR head and park reason a delegate needs; and refuses issue-only actions on a PR.
  • Writes run as the verified caller (pkg/dashboard/admin_mcp.go):

    • adminMCPWriteRequest serves the confirmed write through roleEnforcement → securityHeaders → mux. It carries the user, role and verified-owner marker that authenticate set on the outer /api/admin/mcp request, the same ones the read tools already carry.
    • The client never asserts an identity: authenticate stripped inbound copies before the outer request reached the handler. A dashboard-token caller still runs as the configured owner, as before.
    • Writes are unavailable only to a read-only role, or to a request with no verified identity.
  • Confirmation bound to the previewer (pkg/adminmcp): PendingConfirmation.Actor records who previewed. A confirm from anyone else returns ErrConfirmationActor and puts the confirmation back unused.

  • no_merge (api_repo_item_decide_delegated.go): a request with no_merge decides without the merger role. An approval then takes the /lgtm + /approve path instead of an Approve review queued for auto-merge. The flag can only narrow what the caller's role allows.

  • Stdio (cmd/hive-admin-mcp): routes the two new read tools. Its writes still use the dashboard token.

  • Docs: docs/admin-mcp.md and docs/design/admin-mcp.md now cover the tools, the write identity, the new exclusion, and the attribution gap, which is narrowed for the HTTP endpoint.

  • Authentication docs (docs/admin-mcp.md): the guide described only the dashboard token, which a hub-hosted hive does not hand to its users. A new Authentication section covers each deployment:

    • Hub-hosted: Authorization: Bearer <GitHub token>. The hub checks the token against GitHub /user, then the caller's role on the hive (pkg/hub/saas_auth.go:599-626).
    • Self-hosted: the dashboard token, which acts as the owner.
    • Allowlist spoke: a session cookie.

    It adds Claude Code (headersHelper) and omp (!command) configs that read a fine-grained token with no repository permissions from a file at connect time, plus a 401/403 troubleshooting entry.

  • Guide reorganized for readers (docs/admin-mcp.md, separate commit): the content is the same; only the order and layout change.

    • A page index, with the transports, quick start and authentication first.
    • Client configs grouped by client and by hive type.
    • The stdio binary section split into topics.
    • The tool table split by area, with the longest cells moved into notes.
    • The verdicts, write operations and troubleshooting entries as tables.
    • Every code term, link and number from the old text was checked against the new one. Headings other docs link to are unchanged.

Tests

Test Covers
TestStageTrackerReadFilters (11 rows), …StageCountsDescribeWholeBoard, …SummaryAndFullViews, …PagesAndRecent, …RefusesBadArguments every filter, search by linked number, whole-board stage counts, views, paging, refusals
TestItemOpsSendTheDashboardRequests, TestItemDecisionRequests, TestItemDelegateNeverMerges, …NestedPRsAndRerun each op's method, path and body match the dashboard's; each preview can be stored for confirmation
TestItemDecisionRefusals, TestIssueOnlyOpsRefusePullRequests, TestBoardReadFailureNeedsExplicitType merge answers refused, issue-only actions on PRs, missing kind
TestItemDecisionConfirmRecheckNeedsNoBoard ConfirmWrite's provider-less re-check still matches
TestConfirmationIsBoundToThePreviewingActor, TestPendingActorPersists another caller cannot confirm or burn a confirmation
TestAdminMCPWritesRunAsVerifiedCaller end to end through authenticate: hub-proxied alice writes as alice; bob cannot confirm hers; bearer and internal still work
TestAdminMCPWriteCarriesOwnerMarkerOnlyWhenVerified, TestAdminMCPWritesUnavailableReason the owner marker only rides on a verified owner; read-only role refused
TestAdminMCPStageTrackerRead dashboard routing for both read tools, as the caller
TestDelegatedNoMergeNeverQueuesApproval merger + no_merge → no native approval, /lgtm + /approve
TestAdminMCPApproveIsHeldToTheCallersRepoPermission an approve through the MCP is held to the caller's own repo permission: read is refused and nothing is written; write approves and is named
Mutants (16) 16/16 caught
go test adminmcp, cmd/hive-admin-mcp, dashboard, writeback, cmd/hive pass
check-docs-citations.py, check-api-reference-citations.sh, check-docs-links.py pass

TestAdminMCPWritePreviewFailsFastWithoutDashboardBearer is removed. It asserted the old rule that refuses writes to an internal-header caller, and TestAdminMCPWritesRunAsVerifiedCaller now covers that caller succeeding.

Notes

  • Security review wanted: this changes how the HTTP endpoint authenticates a confirmed write. The identity comes only from authenticate on the outer request, and is never taken from the client. The role checks inside each endpoint still apply. A cross-site POST to the endpoint could mint a preview but cannot read its confirmation id, and the id is bound to the previewing user.
  • Not included: the delegate's plan preview (POST …/decide-delegated/plan) is a POST, and the read tools only issue GETs. Display, sound and label-filter settings are presentational, which [RFC] [v6] Operator-facing admin MCP: administer a hive by conversation #8697 already excludes.
  • Hive operators: writes still need HIVE_ADMIN_MCP_ENABLE_WRITES.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

… the verified caller

stage_tracker_read returns the board the Activity monitor draws
(GET /api/stage-tracker) with its filters and search box, and
delegated_decision_status reads a "Let hive decide" job. The monitor's
row actions are write operations under the preview/confirm contract:
repository.rescan and repository.item_{accept_triage,needs_human,
blocker_recheck,blocker_handoff,blocker_close_partial,decision,delegate}.

The merge answers (merge-now, queue-merge) are refused like
queue-automerge (hivecommons#8697), and repository.item_delegate sends the new
no_merge flag so a merger's delegated approval never queues an
auto-merge.

On the HTTP endpoint a confirmed write now runs as the identity
authenticate verified on the /api/admin/mcp request instead of
re-authenticating with the dashboard token alone, so hub-proxied and
session callers can write and are attributed. A pending confirmation is
bound to the actor that previewed it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 6, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 6, 2026
…hosted hives

The guide only described the dashboard token, which a hub-hosted hive
does not hand to its users and which acts as the owner. Add an
Authentication section: hub-hosted hives take Authorization: Bearer
<GitHub token> (checked against GitHub /user, then the caller's role on
the hive), self-hosted hives the dashboard token, allowlist spokes a
session cookie. Client configs for Claude Code (headersHelper) and omp
(!command, run through /bin/sh -c) read a fine-grained, no-permission
token from a file at connect time. Adds a 401/403 troubleshooting entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correctness review (head 6d5ed25). The write-identity change checks out: adminMCPWriteRequest (src/pkg/dashboard/admin_mcp.go:315-329) only re-emits the identity authenticate already set on the outer request (server.go:2186-2188 strips inbound copies first), roleEnforcement still gates read-only roles on the inner POST (server.go:2844-2866), and TestAdminMCPWritesRunAsVerifiedCaller exercises hub-proxied, bearer and internal paths end to end. no_merge is a pure narrowing (api_repo_item_decide_delegated.go:288) and executeDelegatedDecision takes the /lgtm+/approve branch for mergerRole=false (:1024, :1099). No blocker.

One low-severity gap worth closing:

Board unavailability reads as "not on the board" — handleStageTracker answers 200 {"status":"initializing"} before the first snapshot (stage_tracker_build.go:1048-1051) and 503 while a build is in progress (:1056). StageTrackerReadResult (tools_stage_tracker.go:111-114) accepts the initializing body as a board with zero items and drops the status key, so stage_tracker_read reports matched: 0, total_items: 0 as if the monitor were empty. stageTrackerItem (tools_stage_tracker.go:702-712) swallows any provider error and returns nil, so every item preview then says "This item is not on the Activity monitor now" (boardDetails, :721) when the real cause is that the board could not be read. Suggested fix for the read tool:

	body, ok := data.(map[string]any)
	if !ok {
		return CapResult(data, LimitFromArgs(args)), nil
	}
	if _, hasItems := body["items"]; !hasItems {
		if st := stringField(body, "status"); st != "" {
			return refuse("the Activity monitor is " + st + "; retry shortly")
		}
	}

and in boardDetails, distinguish a failed read (stageTrackerItem returning an error, or a sentinel) from a genuine miss so the preview says the board was unavailable rather than that the item is absent.

— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

Same content, easier to follow: a page index; transports, quick start
and authentication first; client configs grouped by client (Claude
Code, omp, other HTTP, stdio) and by hive type; the stdio binary split
into getting it, keeping it current, skew notice and environment; the
tool table split by area with long cells moved to numbered notes;
start-record verdicts and write operations as tables; troubleshooting
as symptom/fix. Headings other docs link to are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v6

Conflicts are checked with every PR merged onto the current tip of v6, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether admin MCP may make a pull request merge-eligible (item_decision approve / item_delegate post /lgtm + /approve, which the merge sweep then merges) given the catalogue's categorical exclusion of queue-automerge as the only merge-causing action.

Routing to a human: this is a merge-policy boundary, not a code defect. The code I read is consistent and tested; the question is whether it should exist.

What I verified in the tree (head 76b2bb7):

  • Writes now run as the verified caller instead of re-authenticating with the bearer token. src/pkg/dashboard/admin_mcp.go:314 (adminMCPWriteRequest) skips authenticate and sets X-Hive-User/X-Hive-Role from provider.user/role. Those come from handleAdminMCP (admin_mcp.go:61) reading headers that authenticate (server.go:2186) had already stripped and re-set only from a proof-bearing proxy, a live session, or the token; /api/admin/mcp is registered on the authenticated mux (server.go:1827) and proxyProofRequired defaults to true (server.go:99). The owner marker is forwarded only when the outer request was verified owner (admin_mcp.go:325), covered by TestAdminMCPWriteCarriesOwnerMarkerOnlyWhenVerified. This is sound.
  • Confirmations are bound to the previewing actor. adminmcp.go:545 refuses a confirm from a different actor and puts the pending record back. Note that Take then Put is not atomic: a mismatched confirm racing the real one can turn the real one into ErrConfirmationMissing. Low; the owner just previews again.
  • The merge exclusion is enforced for merge-now/queue-merge (tools_stage_tracker.go:521) and item_delegate always sends no_merge (tools_stage_tracker.go:616), which api_repo_item_decide_delegated.go:288 honours by dropping the merger role.

The question: item_decision approve on a PR posts /lgtm + /approve, and the preview says so plainly — "the hive's merge sweep merges it once CI is green and the head has soaked" (tools_stage_tracker.go:548). The new exclusion entry (adminmcp.go:111) argues this is different from queueing a merge. Today no admin MCP operation can make a PR merge-eligible (lgtm appears only in the new file); after this PR an MCP client can, and the result is a merge without a further human action. Whether "merge-eligible, sweep merges" falls inside or outside the "only action that directly causes a merge into real code" exclusion is the maintainers' call. For the record, the author is listed under approvers: in OWNERS, so the role being exercised is one they already hold.

Everything else (stage tracker read, delegated status read, docs) I read only at the wiring level; CI was still running when I looked.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

hivecommons-hive Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Needs a decision, not a merge:

  • the reviewer swarm returned requires_human @878103d
  • the review found: the reviewer marked this change high-risk
  • reviewer question: @clubanderson should decide whether admin MCP writes may run as any hive-verified session or hub-proxied identity with the read-write role (this PR), rather than only for callers presenting the dashboard token as before.
  • the automerge lane will not merge this unattended

Head: verdict requires_human @878103d, 48/54 checks green, 6 pending, DCO yes, soak 0s of 10m0s.

How to release it:

  • After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

Updated 2026-11-06 15:46 UTC.

…fore take

Review on hivecommons#16884:
- stage_tracker_read treated the endpoint's {"status":"initializing"}
  answer as a board with no items. It now returns a board_unavailable
  refusal, and an item preview that cannot read the board says so
  (on_board "unknown") instead of "not on the Activity monitor".
- write_confirm took a mismatched actor's confirmation and put it back,
  which could race the owner's confirm. It now checks the actor first
  and never takes another caller's confirmation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@Danathar

Danathar commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Thanks. Both findings are fixed in c5b17dc.

  • Unbuilt board read as empty (adjudicator): stage_tracker_read now answers the endpoint's {"status":"initializing"} (or any body without items) with a board_unavailable refusal instead of an empty board. Item previews keep "could not read the board" (on_board: "unknown") separate from "not on the board", and a decision or delegate without type is refused when the board cannot be read. Tests: TestStageTrackerNotBuiltYet, plus TestBoardReadFailureNeedsExplicitType updated. Mutants for each branch are caught.
  • Take/Put race on a mismatched confirm (swarm review): ConfirmWrite now checks the pending entry's actor before Take, so another caller's confirm never takes the entry and cannot race or burn the owner's. TestConfirmationIsBoundToThePreviewingActor covers it, and a mutant removing the pre-check is caught.

The approve question routed to @clubanderson is a policy decision, so I'm leaving it to the people named in it.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the branch conflicts with the base and needs a rebase

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (10 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intent alignment (read at head c5b17dc)

The diff does what the title and body claim, and I found no gap between them:

  • Writes run as the hive-verified caller: pkg/dashboard/admin_mcp.go:315-328 (adminMCPWriteRequest) re-sets X-Hive-User/X-Hive-Role from the provider, whose values come from headers authenticate already stripped and re-derived (pkg/dashboard/server.go:2186-2188, then 2197-2432). The owner marker is forwarded only when ownerVerified && isOwnerRole (admin_mcp.go:325-327).
  • Merge answers are refused before any request (pkg/adminmcp/tools_stage_tracker.go:66,549-551); item_delegate always sends no_merge (tools_stage_tracker.go:647), and the endpoint narrows mergerRole with it (api_repo_item_decide_delegated.go:288).
  • The deleted TestAdminMCPWritePreviewFailsFastWithoutDashboardBearer is replaced by admin_mcp_activity_test.go:71-160.

One scope note (non-blocking): commit 76b2bb7 "reorganise the guide for people reading it" rewrites 499/347 lines of src/docs/admin-mcp.md with no behavioural tie to the Activity monitor feature. It is disclosed in the body and isolated in its own commit, but under a squash merge that isolation is lost and the feature's doc changes become hard to review against the reorg. Consider landing the reorg as its own docs PR (or first), then rebasing this one onto it.

— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

hivecommons-hive Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from adjudicator-3 (folded here because this head already carries its hive review):

docs-currency review (head c5b17dc)

The guide, design record and changelog match the code I read: tool/op names, the item_decision answer list and merge-now/queue-merge refusal, no_merge, the ErrConfirmationActor text quoted in Troubleshooting, the writes_unavailable_reason wording, the permission table against api_repo_item_*.go / api_review_pipeline.go / item_blocker.go, the hub's 5-minute token cache (pkg/hub/saas_auth.go:694), the hivectl.md#credentials anchor, and the headings other docs link to.

One operator-facing text defect:

repository.rescan preview promises a queued rescan that the handler never queues — src/pkg/adminmcp/tools_stage_tracker.go:442 says "A rescan already running is not restarted; the next one is queued." handleReposRescan (src/pkg/dashboard/api_repos_rescan.go:29-32,54-58,18) does the opposite: an in-flight scan answers in-progress with the previous counts and a scan finished less than 30 s ago answers debounced with retry_after_s; both are documented no-ops, nothing is queued. An operator confirming on the strength of the preview would believe a rescan is coming when it is not.

	return WritePreview{Operation: WriteOpRepositoryRescan, Summary: "Rescan every watched repository now", Target: "all watched repositories", Request: WriteRequest{Method: http.MethodPost, Path: "/api/repos/rescan", Body: map[string]any{}}, Effects: []string{"The hive re-reads issues and pull requests on its watched repositories now instead of on its next scheduled pass. If a rescan is already running, or one finished less than 30 seconds ago, nothing new is started: the hive answers in-progress or debounced (with retry_after_s) and the previous scan's counts, and no rescan is queued."}, WideningDisclosure: "Hive-wide: the rescan covers every watched repository, as the dashboard's button does, but changes no item by itself.", ConfirmationMessage: "Confirm rescanning the watched repositories now.", Details: map[string]any{}}, nil

The design doc's "re-evaluate now | none beyond write access" row is correct (api_repos_rescan.go:78-81).

Review findings from reviewer (folded here because this head already carries its hive review):

Conclusion: I found no defect in the code; the auth-path change does what the body says and the safeguards it relies on are real. What it changes is policy — who may write through admin MCP — and that is a maintainer call, not mine. Details below so the decision can be made without re-deriving them.

What I verified (read at head ca9a614 and v6)

  • Identity on the write is hive-verified, not client-asserted. adminMCPWriteRequest (src/pkg/dashboard/admin_mcp.go:320-336) injects X-Hive-User/X-Hive-Role from provider.user/provider.role, which handleAdminMCP reads from the outer request after authenticate ran. authenticate deletes inbound X-Hive-User, X-Hive-Role and X-Hive-Owner-Role-Verified before any dispatch (server.go:2186-2188) and re-sets them only from proxy proof, session or token (server.go:2197-2272). So the comment's claim that "inbound copies were stripped" is accurate.
  • Owner marker is not forged. The inner request only gets X-Hive-Owner-Role-Verified when p.ownerVerified && isOwnerRole(p.role), and ownerVerified is derived from the marker authenticate itself set.
  • Confirmations are actor-bound. PendingConfirmation.Actor is recorded at preview and compared at confirm (src/pkg/adminmcp/adminmcp.go, the ErrConfirmationActor hunks), so a confirmation previewed by one identity cannot be executed by another.
  • no_merge can only narrow. mergerRole := !body.NoMerge && RoleAtLeast(...) (api_repo_item_decide_delegated.go:288); repository.item_delegate always sends it (tools_stage_tracker.go, body map with "no_merge": true), and TestDelegatedNoMergeNeverQueuesApproval covers the merger-role case.
  • Open-spoke fallback preserved. With no verified identity the write still re-enters authenticate with the caller's Authorization, as before.

The decision

Before: a confirmed admin-MCP write re-authenticated with the dashboard token only, so in practice only the token holder (recorded as the configured owner) could write, and direct-route spokes refused writes outright. After: any identity authenticate admits with role ≥ read-write — a device-flow session on a direct-route spoke, or a hub-proxied user — can preview and confirm Re-evaluate / Accept triage / Mark needs-human / blocker actions / Decide / Let-hive-decide, attributed to that user. That is a deliberate widening of the write surface to session and hub identities and is the question a maintainer needs to answer; the merge exclusion is unaffected.

Danathar is an approver and the author, so I've addressed the question to another approver. I have not approved or requested changes.

Evidence bundle `#16884ca9a614` sha256:849a16684664bfa5a63fcf7545b7a50eae3cdfa7585a9517d90bcba8f0c892c8 — download from the dashboard or `hivectl review evidence #16884`.

…cker

src/docs/admin-mcp.md: kept the reorganized guide and carried over v6's changes to it: ping and notification answers (hivecommons#16893), version_read hash/short (hivecommons#16890), settings_read takes no limit and the triggers section (hivecommons#16892), What a read masks (hivecommons#16889), and write tools always listed with metadata.preview.enabled (hivecommons#16890); the troubleshooting row follows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 6, 2026
…r's repo permission

Pins the decision on approve: it stays, constrained to the caller's own
rights. Through the full auth chain into the real decision route, a
caller with read access on the repository is refused with "write
permission required" and nothing is written; a caller with write access
approves, and the /lgtm comment names them. The guide's "Who a write runs
as" says the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@Danathar

Danathar commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Decision on the open question (may the admin MCP make a pull request merge-eligible): yes, as long as it is held to the rights of the person operating the MCP.

That is how it works on this branch, and e38fc6b pins it with a test.

  • A write runs as the verified caller. The confirmed write carries the identity authenticate verified on the request. It is never one the client asserts, and a confirmation is bound to whoever previewed it.

  • Approve uses the same check as the dashboard button. repository.item_decision approve and repository.item_delegate go through POST …/decision and …/decide-delegated. Both call canToggleRepoHold, which allows a verified owner, the repository's owner, or a user whose own GitHub permission on that repository is write, maintain or admin. A read-only role on the hive is stopped earlier, by roleEnforcement.

  • New test, TestAdminMCPApproveIsHeldToTheCallersRepoPermission. It goes through the full auth chain into the real decision route:

    • a caller with read on the repository is refused with "write permission required", and nothing is written;
    • a caller with write approves, and the /lgtm comment names them.

    It fails if the permission check is removed, and it fails if the write runs as anyone but the caller.

  • The MCP stays narrower than the dashboard. merge-now and queue-merge are still refused, and a delegated decision sent through the MCP carries no_merge, so it never queues an auto-merge.

docs/admin-mcp.md ("Who a write runs as") now says this in plain words.

@Danathar

Danathar commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Maintainer approval (@Danathar): I approve this change. It can go forward once CI is green on the current head (e38fc6b8a) and the hive's review of that head finds no blocker.

My earlier comment covers the open question about approve: it stays, held to the operator's own permissions, and TestAdminMCPApproveIsHeldToTheCallersRepoPermission pins that. GitHub does not let me approve my own PR, so this comment is my approval.

The repository.rescan preview said "the next one is queued", but
handleReposRescan never queues: a running scan answers in-progress and one
finished under 30 s ago answers debounced with retry_after_s, both no-ops.
Use the hive reviewer's wording (adjudicator-3 on c5b17dc) and pin it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@Danathar

Danathar commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

The rescan preview finding from adjudicator-3 (head c5b17dc) is fixed in 878103d. The text was wrong, and I checked that against the handler: handleReposRescan answers in-progress or debounced (with retry_after_s) and never queues a second scan. The preview now uses your suggested wording.

TestRescanPreviewDoesNotPromiseAQueuedRescan pins it; it fails on the old text and passes on the new. ./pkg/adminmcp/ passes.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether confirmed admin-MCP writes may run on the identity authenticate verified for the outer /api/admin/mcp request (no re-authentication on the inner write), as this PR implements.

Routing to a maintainer rather than confirming: this changes how a confirmed admin-MCP write authenticates, which is a trust decision, not a code-correctness one. The author asks for a security review in the body, and I agree one is needed. What I verified on e38fc6b:

The new write identity is hive-verified, not client-asserted.

  • src/pkg/dashboard/admin_mcp.go:63-70 — the provider's user/role/ownerVerified are read from the outer request after it passed authenticate.
  • src/pkg/dashboard/server.go:2186-2188 — authenticate deletes inbound X-Hive-User, X-Hive-Role and X-Hive-Owner-Role-Verified unconditionally, and re-sets them only once a hub-proxy proof (secureCompare(proof, s.authToken)) or a server-side session has been checked. So a client cannot smuggle an identity into the provider.
  • src/pkg/dashboard/admin_mcp.go:323-337 (adminMCPWriteRequest) — with a verified user+role, the inner write skips authenticate and goes straight to roleEnforcement → securityHeaders → mux with those headers injected. With no verified identity it falls back to exactly the old path (re-enter authenticate with the caller's Authorization), so dashboard-token and open-spoke behaviour is unchanged.

no_merge can only narrow. src/pkg/dashboard/api_repo_item_decide_delegated.go:288 — mergerRole := !body.NoMerge && RoleAtLeast(..., RoleMerger) && …; the flag removes the merger path and never adds anything.

What a human has to decide, in one sentence: is it acceptable that a hub-proxied or session caller's outer authentication now authorises the inner confirmed write (bypassing authenticate on that hop), given every endpoint's own role check still runs via roleEnforcement and the pending-confirmation is bound to the previewing actor (PendingConfirmation.Actor)?

Two facts for that decision, no opinion attached:

  • @Danathar is listed in OWNERS as an approver, so the approval should come from a different approver.
  • The removed TestAdminMCPWritePreviewFailsFastWithoutDashboardBearer encoded the old rule this PR deliberately reverses; its replacement TestAdminMCPWritesRunAsVerifiedCaller covers the new one.

I found no defect in the parts I read (the auth path, the no_merge flag, the provider wiring). I did not read tools_stage_tracker.go (~1k lines of filters/paging) line by line; CI is green on it.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit 127039f into hivecommons:v6 Nov 6, 2026
68 of 69 checks passed
@hivecommons-hive

Copy link
Copy Markdown
Contributor

merged by Hive trusted-author auto-merge: author @Danathar holds role owner and GitHub permission maintain on repo; CI green at ca9a614.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether the admin MCP may issue repository.item_decision with decision: approve — which posts /lgtm + /approve as the caller and lets the merge sweep merge the PR — given the PR's stated contract that admin MCP never merges.

I read the identity change and the write surface rather than the whole 684-line tracker file; no defect found in what I read, but this expands the admin MCP's merge-adjacent authority and that is a maintainer call.

What I verified

  • src/pkg/dashboard/admin_mcp.go adminMCPWriteRequest: a confirmed write now carries X-Hive-User / X-Hive-Role / the verified-owner marker copied from the outer request. Those headers are the ones authenticate itself set — inbound copies are deleted at server.go:2186-2188 before any of the verified paths (:2197-2272) set them — so the inner request cannot run as an identity the client asserted. The pre-existing path (re-enter authenticate with the caller's Authorization) is kept for requests with no verified identity.
  • src/pkg/adminmcp/adminmcp.go: PendingConfirmation.Actor is recorded at preview and compared before Take and again after, so a confirmation previewed by one caller cannot be burned or executed by another (ErrConfirmationActor).
  • tools_stage_tracker.go:553: merge-now / queue-merge are refused at preview, and item_delegate sends no_merge: true (:647), which api_repo_item_decide_delegated.go honours by clearing mergerRole so a delegated approval never queues an auto-merge.
  • admin_mcp_approve_permission_test.go shows a read-only caller's approve is refused by the decision route and a writer's approve is attributed to @writer.

The decision

The body's headline is "Never merges", and the MCP itself does not merge. But repository.item_decision with decision: approve is offered (tools_stage_tracker.go:582: "Posts /lgtm and /approve as your decision; the pull request becomes merge-eligible, and the hive's merge sweep merges it once CI is green"). The preview discloses this, and the permission check is the same one the dashboard's Approve button uses, so this is consistent — but it means an MCP client acting for a merger-role user can cause a merge one step removed, which queue-automerge's exclusion (#8697) was written to prevent. Whether that distinction is the intended line, or whether approve should join merge-now/queue-merge in the refusal list, is the one question a maintainer needs to answer before this lands.

I have not read the full stage-tracker read tool or the ~900 lines of docs changes.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant