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

docs/concepts/tools.md

@@ -5,11 +5,9 @@ harness resolves against the server, distinct from any MCP tools a task might
 also carry. Each tool carries its own description at the call site; this doc is
 the higher-level map: what the set covers and the general flow of using it.
 
-> **Keep this current as tools land.** The comms and lifecycle tools below have
-> shipped and are documented here. The forge tools and the subscription tools
-> are landing; as each lands,
-> add it to the right group below and note its flow. A tool that has shipped but
-> is not listed here is a documentation gap to close.
+> **Keep this current as tools land.** The comms, lifecycle, and forge tools
+> below have shipped and are documented here. A tool that has shipped but is
+> not listed here is a documentation gap to close.
 
 ## Comms — how agents talk
 
@@ -62,6 +60,15 @@ a subagent spawn.
   container + session). Spawning a child Manager needs operator approval first.
 - **`agents_despawn_peer`** — tear a standing agent down when its lane closes.
 
+## Forge — working with issues and pull requests
+
+- **`forge_get_issue`, `forge_get_pull_request`, `forge_list_issues`** — read forge state.
+- **`forge_comment_on_issue`, `forge_comment_on_pull_request`, `forge_submit_review`** — write comments and reviews under server-stamped agent attribution.
+- **`forge_create_issue`, `forge_create_pull_request`** — create forge artifacts with idempotent retries.
+- **`forge_transition_issue_state`, `forge_transition_pull_request_state`** — change artifact state.
+- **`forge_subscribe`, `forge_unsubscribe`** — manage notifications for forge artifacts.
+- **`forge_mirror_messages`** — mirror one visible topic or selected messages to an AUTO-enabled issue or pull request. Choose exactly one source. A topic mirrors its newest 50 messages; selected messages must come from one channel. An optional channel is a visible channel name, and an optional note appears above the messages. The Server checks source visibility, AUTO mode, repository scope, and idempotent delivery before posting.
+
 ## The general flow
 
 1. **Orient** — `compass_roster` to see who is around; read your home channel

docs/specs/product/compass.md

@@ -1057,6 +1057,62 @@ same ref SHALL be refused while the first user's mirror exists.
 Topic mirrors SHALL carry at most the newest 50 messages. If a topic has more
 than 50, the mirror SHALL state, "Showing the newest 50 messages."
 
+### Requirement: Agent mirror tools may mirror visible messages to AUTO forge targets
+
+The agent `forge_mirror_messages` tool SHALL accept exactly one source: a topic
+or one to fifty message IDs from one channel. The caller SHALL be able to see
+the source channel. The tool SHALL check the target with the agent mirror policy
+and SHALL post only when the target is in AUTO mode; MANUAL and OFF SHALL be
+refused. The server SHALL render a topic's newest 50 messages, include the
+optional note, drop whole oldest messages when the forge body limit requires it,
+and state how many were dropped. Re-mirroring the same source to the same target
+SHALL edit the existing comment. A completed retry with the same
+`client_request_id` SHALL return the stored comment reference without posting
+again; a pending retry SHALL return unavailable, and a failed retry SHALL
+return its stored error. A target that is a tracked pull request SHALL return a
+PR-comment result; another target SHALL return an issue-comment result.
+
+The optional `channel` selector SHALL be a channel name, never a channel ID.
+When it is omitted, the server SHALL take the channel from the topic or the
+messages. When it names a channel that does not hold the source, or one the
+agent cannot see, the server SHALL return not-found. Every agent mirror post
+SHALL name the agent's real posting session in its owner header; a row with no
+session SHALL fail without posting. The server SHALL store the source on the
+row, so a mirror still pending at a restart is redriven with the same body.
+A redrive SHALL check visibility again, and SHALL fail the row without posting
+when the agent can no longer see the source.
+
+#### Scenario: A retry returns the first mirror result
+
+- **Given** an agent mirror request that has already delivered a comment
+- **When** the agent retries it with the same `client_request_id`
+- **Then** the server returns the stored comment reference and the forge sees
+  only one post
+
+#### Scenario: A topic is mirrored again to the same target
+
+- **Given** a topic already mirrored to a forge target
+- **When** the agent mirrors that topic to the same target again
+- **Then** the server edits the existing comment instead of creating another
+
+#### Scenario: An agent cannot mirror to a MANUAL or OFF target
+
+- **Given** a forge target configured as MANUAL or OFF
+- **When** an agent calls `forge_mirror_messages` for that target
+- **Then** the server refuses the call without posting a comment
+
+#### Scenario: An agent cannot mirror messages from a channel it cannot see
+
+- **Given** a source topic or message set in a channel the agent cannot see
+- **When** the agent calls `forge_mirror_messages`
+- **Then** the server returns not-found without revealing the channel or messages
+
+#### Scenario: A pending mirror is redriven after a restart
+
+- **Given** an agent mirror row that was claimed but not posted before a restart
+- **When** the restarted server drives the agent's open rows
+- **Then** it posts the same body, stamped with the session that made the call
+
 ### Requirement: Automatic mirroring follows the ask's explicit ref
 
 An ask with an explicit ref to an enabled AUTO coordinate SHALL be mirrored