feat(mirror): agent forge_mirror_messages tool with real-session attribution (RIG-5174) by rigel-mintaka · Pull Request #2319 · RigelBuild/compass

rigel-mintaka · 2026-10-15T22:16:03Z

This PR is part of a stack containing 4 PRs:

main
feat(ui): board summary badges in the sidebar and FleetPane (RIG-5177) #2290
feat(board): show asks and their forge mirror state on boards (RIG-5173) #2292
feat(ui): add the agent board panel and tasks search over ListAgentBoards (RIG-5409) #2300
"feat(mirror): agent forge_mirror_messages tool with real-session attribution (RIG-5174)" (this PR)

Summary

Adds the agent tool forge_mirror_messages and the forge arm mirror_messages = 16. An agent mirrors one visible topic, or 1 to 50 selected messages, to an auto-mode issue or PR as one comment. Mirroring the same source again edits that comment.
Retries are idempotent on client_request_id. A retry returns the stored result (done, pending or failed, with its code) before any policy or visibility check. A retry with a different target is refused. Each re-mirror key is reserved once in forge_mirror_requests, so a retry never edits twice.
Attribution (RIG-5431): every agent mirror post names the real session in its owner header; the literal mirror session is gone. The direct call uses the caller's session. Queued ask mirrors use the posting session that RelayCommsCall verified, carried to the store in the request context. An agent row with no session fails rather than posting unattributed.
Redrive (RIG-5439): forge_mirrors.source_payload holds the resolved channel, the topic or message IDs, and the note. A redrive after restart rebuilds the body from it and re-checks visibility.
Channel selector (RIG-5430): channel is a channel name. When omitted it is derived from the source. A mismatched, invisible or unknown name all return not_found.

Verification

golangci-lint run 0 issues (default and pgtest tags); nilaway clean; gofmt clean; go build; unit tests.
Full pgtest runs pass for server, internal/store, internal/mirror, internal/runnerhub and internal/comms. The round-3 fixes reran the targeted mirror/store set.
compass-agent bun tests 868/868. The native tool count assertion moves from 27 to 28.
compass-proto:drift, typecheck, and rumdl on the spec.
Red first: each new behaviour was sabotaged and its test failed before the fix was restored.
Review: three rounds.
- Round 1: five medium findings on retry semantics and a deleted test.
- Round 2: one medium cross-table key race.
- Round 3: lows only.
- All findings are fixed.

Risks

0001_init.sql is edited in place, so dev databases need a reset; no database is deployed.
An agent ask posted outside the relay would now fail its mirror instead of posting as mirror. The only agent post path is the relay.

Compatibility

New proto arm and message; existing arms are unchanged.
forge_mirrors gains columns, and there is a new table forge_mirror_requests, covered by RLS.
The mirror.Poster.PostMirror signature gains session; this is an internal interface.

Documentation

docs/specs/product/compass.md: the agent mirror requirement and its scenarios.
docs/concepts/tools.md: the new tool.

Open reading on RIG-5439: the payload stores the resolved channel ID, not the caller's name, because a channel can be renamed. Matt left this sub-question open.

Refs RIG-5174, RIG-5431, RIG-5439, RIG-5430

linear-code · 2026-10-15T22:16:10Z

github-actions · 2026-10-15T22:17:47Z

Compass engineering docs preview: https://compass-comms-rig-5174-mirro.compass-eng-docs.pages.dev

Deployed from compass-comms/rig-5174-mirror-tool at 78d5c27.

Changed pages:

rigel-mintaka · 2026-10-15T23:17:43Z

Review status at head 8bd607f: the head-check round found one medium (a concurrent same-key duplicate can be driven instead of returning the stored result) plus two low test gaps. A fix is in progress, so this PR stays draft.

rigel-mintaka · 2026-10-16T00:02:59Z

Head 782d8ca fixes the same-key loser being driven: claims now report a resolution, and only Inserted or Remirrored is driven. A review round at 782d8ca found two mediums: a request-key row inserted after the early lookup resolves as Conflict instead of Reserved, and the handler's conflict branch is untested. Fixes are in progress, so the PR stays draft.

rigel-mintaka · 2026-10-16T01:51:28Z

Review loop is all-clear at head 478bc1ad. CI is green on all 11 checks.

Round	Head	Result
R4	`8bd607f`	1 medium (same-key loser was driven), 2 low: fixed in `782d8ca`
R5	`782d8ca`	2 medium (racing keyed insert came back as Conflict; conflict branch untested), 3 low: fixed in `05d58f3`
R6	`05d58f3`	4 low (re-mirror key reservation; unreachable test; comments): fixed in `9dbb5c5`
R7	`9dbb5c5`	2 low (comments; named boolean): fixed in `478bc1a`
R8	`478bc1a`	4 lenses, 0 findings, with a per-lens justification

Base compass-ux/5409-board-panel (#2300). It lands at the top of the board line.

…ibution (RIG-5174) Adds the mirror_messages forge arm and the forge_mirror_messages agent tool. An agent mirrors one visible topic or 1-50 selected messages to an auto-mode issue or PR as one comment; a retry with the same client_request_id returns the first result and never posts twice. - Every agent mirror post stamps the real session: the direct call's session, or for queued ask mirrors the relay-verified posting session (RIG-5431). An agent row with no session is refused, never posted as `mirror`. - forge_mirrors gains session_id and source_payload; a redrive after restart rebuilds the body from the payload and re-checks visibility (RIG-5439). - The source channel is a channel name resolved for the caller (RIG-5430). Co-authored-by: Matt Wilkinson <matt@rigel.build>

- A same-key retry returns the stored result before policy and visibility checks, refuses a different target, and classifies from the stored target. - forge_mirror_requests records each re-mirror key, so retrying it never bumps or edits again. - forge_mirrors.last_error_code keeps a failure's code for retries. - Restore the forge tool repo-validation tests and tighten the redrive tests. Co-authored-by: Matt Wilkinson <matt@rigel.build>

…mirror (RIG-5174) An agent claim now reserves its client_request_id in forge_mirror_requests in the same transaction as the row, so a claim and a re-mirror racing on one key resolve to one row. ForgeMirrorByRequest reads only the reservation. Adds the table to the RLS floor test and real whitespace-repo checks per forge schema. Co-authored-by: Matt Wilkinson <matt@rigel.build>

…G-5174) A claim that loses the request-key race returns the reserved row; the handler now reads the reservation, not the row's own key, so the racing call gets the stored result. Adds deterministic coverage for both reservation-race branches. Co-authored-by: Matt Wilkinson <matt@rigel.build>

A concurrent same-key duplicate that loses the key reservation now gets the stored result instead of leasing and re-posting the row. Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

A request key that names a row after the claim's lookup missed now returns that row's stored outcome instead of a source conflict. Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

rigel-mintaka · 2026-10-16T02:23:54Z

Rebased with the line onto main 888ac07. New head 78d5c27 on #2300 ed3987f. git range-diff against 478bc1a shows all 8 commits identical ('='). pgtest: comms, runnerhub, server, store and mirror ok on the rebased line. Pre-push moon ci passed. Waiting on CI at this head.

rigel-mintaka · 2026-10-16T04:04:06Z

CI is green at 78d5c27: 11 pass, 0 fail, 0 pending, after re-running the cancelled duplicate. The patch matches the reviewed 478bc1a (range-diff '=' on all 8 commits).

rigel-mintaka · 2026-10-16T04:08:12Z

Matt's ruling, given in the Compass owner session on 2026-10-16: PRs may still edit go/internal/store/migrations/0001_init.sql in place, because the dev environment has not been redeployed yet. #2244 (RIG-4897), which turns migration immutability back on, is held until Matt is ready to redeploy. So compass#2319 must merge before #2244. Merge order: board line (tip #2319), then #2244, then the mattfw dev DB wipe (RIG-4927).

rigel-mintaka marked this pull request as ready for review October 16, 2026 01:51

rigel-mintaka requested a review from mattwilkinsonn as a code owner October 16, 2026 01:51

rigel-mintaka and others added 8 commits October 15, 2026 21:55

fix(mirror): drive only the claim that reserved the key

c6ce361

A concurrent same-key duplicate that loses the key reservation now gets the stored result instead of leasing and re-posting the row. Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

fix(mirror): resolve a racing same-key insert as reserved

9e039f0

A request key that names a row after the claim's lookup missed now returns that row's stored outcome instead of a source conflict. Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

fix(mirror): prefer a key reserved by a racing re-mirror over a conflict

dbe32a3

Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

docs(mirror): state the claim source rule in resolution comments

78d5c27

Refs: RIG-5174 Co-authored-by: Matt Wilkinson <matt@rigel.build>

rigel-mintaka force-pushed the compass-comms/rig-5174-mirror-tool branch from 478bc1a to 78d5c27 Compare October 16, 2026 02:23

mattwilkinsonn added this pull request to stack #2242 October 16, 2026 23:10

mattwilkinsonn approved these changes Oct 16, 2026

View reviewed changes

mattwilkinsonn merged commit 7b648a1 into main Oct 16, 2026
36 of 48 checks passed

mattwilkinsonn deleted the compass-comms/rig-5174-mirror-tool branch October 16, 2026 23:11

rigelbuild-compass-ci Bot mentioned this pull request Oct 16, 2026

chore(main): release 0.3.1 #1269

Merged

Navigation Menu

Repository navigation

feat(mirror): agent forge_mirror_messages tool with real-session attribution (RIG-5174) - #2319

feat(mirror): agent forge_mirror_messages tool with real-session attribution (RIG-5174)#2319
mattwilkinsonn merged 8 commits into
compass-ux/5409-board-panelfrom
compass-comms/rig-5174-mirror-tool

rigel-mintaka commented Oct 15, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Oct 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 15, 2026 •

edited

Loading

Uh oh!

rigel-mintaka commented Oct 15, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rigel-mintaka commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Risks

Compatibility

Documentation

Uh oh!

linear-code Bot commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rigel-mintaka commented Oct 15, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

rigel-mintaka commented Oct 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rigel-mintaka commented Oct 15, 2026 •

edited

Loading

linear-code Bot commented Oct 15, 2026 •

edited

Loading

github-actions Bot commented Oct 15, 2026 •

edited

Loading