pog-mcp 0.6.0 → 0.7.0

package/dist/server.js

@@ -196,6 +196,22 @@ const FORUM_MAX_REPORT_ROUNDS = 3;
  * exact shape of failure this codebase keeps paying for.
  */
 const FORUM_MAX_EXTRA_SQUADS_SCANNED = 10;
+/**
+ * How long catch_up will spend looking for a previewable cup fixture.
+ *
+ * Well under one client timeout (30s), because this is enrichment: the caller
+ * asked for match results, and a stalled forum must not delay them. Losing the
+ * prompt costs nothing that the next call does not offer again.
+ */
+const FORUM_FIXTURE_LOOKUP_BUDGET_MS = 4_000;
+/**
+ * How long a "this deployment supports it" answer is trusted.
+ *
+ * Short, because the thing it authorizes is destructive against an older route:
+ * a rollback inside this window is the one case where the guard fails open. Long
+ * enough that a page-by-page read does not re-ask every time.
+ */
+const FORUM_CAPABILITY_CACHE_MS = 60_000;
 /**
  * Why this match is worth a post, or null when it is not.
  *
@@ -587,7 +603,135 @@ function forumScopeIdError(scopeType, scopeId) {
  * Returning null when nothing is waiting is deliberate. A block that appeared on
  * every call, saying there was nothing to do, would be trained away in a week.
  */
-function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads = 0, unexaminedCandidates = 0, failedSquadHistories = 0) {
+/**
+ * Was this post written before `boundaryIso`?
+ *
+ * ONE function because three places ask it and they must not disagree: the
+ * write path deciding whether a new post is a preview or a report, catch_up
+ * deciding whether a fixture still needs a preview, and the report scan
+ * deciding whether a match has already been written up. They disagreed once —
+ * the write path used "the match is not complete" as a stand-in for "before
+ * kickoff", which is false for a fixture that has kicked off and is still
+ * being played, so a post filed then counted as a preview when written and as
+ * a report when read, and the real report was refused as a duplicate.
+ *
+ * False when either timestamp is unreadable: that collapses the two slots back
+ * into one, which costs a post nobody could have written twice. Defaulting the
+ * other way would hand out a second slot on bad data.
+ */
+/**
+ * Is this wallet a synthetic one that no person reads mail for?
+ *
+ * TWO formats, because two things create bots: the scheduler tops a cup up to
+ * 48 entrants with `AIBot:<label>:<hash>`, and seed-playoff-ai.ts seeds the
+ * ladder with `ai-bot-NNNN` — and a seeded bot that climbs to Division 1 is
+ * carried into the cup unchanged. Checking only the first called those human
+ * and promised an answer from an inbox nobody opens.
+ *
+ * Neither prefix can collide with a real base58 wallet: one contains ':' and
+ * the other '-'.
+ */
+function isBotOwnerWallet(ownerWalletAddress) {
+    return ownerWalletAddress.startsWith('AIBot:') || ownerWalletAddress.startsWith('ai-bot-');
+}
+/** Has this fixture's scheduled kickoff passed? False when it cannot be read. */
+function kickoffIsPast(kickoffAt) {
+    return typeof kickoffAt === 'string' && !writtenBefore(new Date().toISOString(), kickoffAt);
+}
+function writtenBefore(createdAt, boundaryIso) {
+    if (boundaryIso === null)
+        return false;
+    const boundary = Date.parse(boundaryIso);
+    const at = Date.parse(createdAt);
+    if (Number.isNaN(boundary) || Number.isNaN(at))
+        return false;
+    return at < boundary;
+}
+/**
+ * The next cup fixture one of these squads is in and nobody has played yet.
+ *
+ * This is what makes a preview possible at all: the bracket is drawn when the
+ * cup opens and its matches kick off two minutes apart, so for most of a cup
+ * there is a fixture whose opponent is known and whose result is not. Without
+ * surfacing it, an agent has no way to notice that window — get_cup exists, but
+ * nothing tells it to look, and by the time a match shows up in history the
+ * window has closed.
+ *
+ * Returns null on any failure. A cup nobody could read is not a reason to fail
+ * catch_up, whose match results are why the agent called.
+ */
+async function nextCupFixture(client, owned, cupDate, signal) {
+    if (owned.size === 0)
+        return null;
+    try {
+        const bracket = await client.cupBracket(cupDate, signal);
+        const fixtures = (bracket.matches ?? []).filter((fixture) => {
+            const row = fixture;
+            if (row.status === 'complete')
+                return false;
+            return ((typeof row.homeTeamId === 'string' && owned.has(row.homeTeamId))
+                || (typeof row.awayTeamId === 'string' && owned.has(row.awayTeamId)));
+        });
+        // Soonest first. A knockout slot with no teams resolved yet sorts by the
+        // same key and is filtered out below, since it has no opponent to name.
+        fixtures.sort((a, b) => String(a.kickoffAt ?? '').localeCompare(String(b.kickoffAt ?? '')));
+        for (const fixture of fixtures) {
+            const mine = typeof fixture.homeTeamId === 'string' && owned.has(fixture.homeTeamId);
+            const other = mine ? fixture.awayTeamId : fixture.homeTeamId;
+            // Both sides ours is a fixture between two of this wallet's squads: there
+            // is nobody to address, so it is not a conversation starter.
+            if (typeof other !== 'string' || owned.has(other))
+                continue;
+            const kickoffAt = typeof fixture.kickoffAt === 'string' ? fixture.kickoffAt : null;
+            // Already kicked off and still being played: nothing left to predict, and
+            // post_to_forum refuses it. Pointing an agent at a call that cannot
+            // succeed is how instructions stop being read.
+            if (kickoffAt === null || kickoffIsPast(kickoffAt))
+                continue;
+            // Already previewed. Without this the same fixture came back on every
+            // catch_up and every attempt was rejected as a duplicate — an instruction
+            // that fails as soon as it is followed.
+            const room = await client.forumPosts({
+                scopeType: 'match',
+                scopeId: fixture.matchId,
+                limit: FORUM_READ_MAX_LIMIT,
+                signal,
+            });
+            const previewed = room.posts.some((existing) => existing.deletedAt === null
+                && existing.replyToPostId === null
+                && owned.has(existing.authorTeamId)
+                && writtenBefore(existing.createdAt, kickoffAt));
+            if (previewed)
+                continue;
+            // Is the squad you drew a person?
+            //
+            // Production tops every cup up to 48 entrants with deterministic AI
+            // teams. Their owner wallet is a synthetic `AIBot:...` that cannot
+            // authenticate and runs no agent, so a mention reaches an inbox nobody
+            // opens. Predicting the match is still worth doing; being told somebody
+            // will answer is not, and an agent that waits for a reply that cannot
+            // come learns the forum does not work.
+            // Three states, not two. A failed or empty lookup used to fall through to
+            // "human", which is the fail-open direction: it promises a reader on no
+            // evidence. Unknown says only what is known — post anyway, expect nothing.
+            const opponentKind = await client
+                .team(other, signal)
+                .then((team) => {
+                const owner = team.ownerWalletAddress;
+                if (typeof owner !== 'string' || owner.length === 0)
+                    return 'unknown';
+                return isBotOwnerWallet(owner) ? 'bot' : 'human';
+            })
+                .catch(() => 'unknown');
+            return { matchId: fixture.matchId, opponentTeamId: other, kickoffAt, opponentKind };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads = 0, unexaminedCandidates = 0, failedSquadHistories = 0, unreadOnMySquads = 0, busiestSquadRoom = null, upcomingFixture = null) {
     const waiting = unreadMentions ?? 0;
     if (waiting === 0
         && unreadIssueReplies === 0
@@ -595,6 +739,8 @@ function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, wort
         && unreadError === null
         && unscannedSquads === 0
         && failedSquadHistories === 0
+        && unreadOnMySquads === 0
+        && upcomingFixture === null
         && unexaminedCandidates === 0) {
         return null;
     }
@@ -615,6 +761,42 @@ function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, wort
             'store from forum posts, and read_mentions does not return them. Tell the person you work ' +
             'for to open the forum\u2019s issue view; do not go looking for a tool that does it.');
     }
+    if (unreadOnMySquads > 0) {
+        // An instruction is allowed HERE — nothing in this block was written by
+        // anybody else. It carries counts and ids, never a body or a squad name, so
+        // there is no stranger's sentence sitting beside ours.
+        lines.push(`${String(unreadOnMySquads)} unread ${unreadOnMySquads === 1 ? 'post' : 'posts'} in your own ` +
+            "squad's room. A post there does not have to tag you to be about you, which is why it " +
+            'is counted separately — but a post that DOES tag you is counted in both, so these two ' +
+            'numbers can describe the same conversation rather than two. ' +
+            (busiestSquadRoom === null
+                ? ''
+                : `read_forum(scopeType="team", scopeId="${busiestSquadRoom}") to see it, then ` +
+                    'reply_to_post. ') +
+            'Being written about and never answering is how a squad stops being written about.');
+    }
+    if (upcomingFixture !== null) {
+        // The window, named while it is still open.
+        //
+        // A cup fixture is the one match in this game you can see coming: drawn when
+        // the cup opens, kicking off minutes later. Said only here, because by the
+        // time the result reaches history the chance to say anything beforehand is
+        // gone — and an agent that is never told about the window will never look
+        // for it.
+        lines.push(`You have a cup fixture that has NOT been played: ${upcomingFixture.matchId}` +
+            `${upcomingFixture.kickoffAt === null ? '' : `, kicking off ${upcomingFixture.kickoffAt}`}. ` +
+            `post_to_forum(aboutMatchId="${upcomingFixture.matchId}") to say what you think will ` +
+            'decide it. ' +
+            (upcomingFixture.opponentKind === 'bot'
+                ? 'The squad you drew is one of the AI teams that fill the cup — it is tagged, but ' +
+                    'nobody reads that inbox, so expect no answer from them. Other managers still read ' +
+                    'the room. '
+                : upcomingFixture.opponentKind === 'human'
+                    ? 'The squad you drew is tagged automatically, so they see it. '
+                    : 'The squad you drew is tagged automatically. Whether anybody reads that inbox could ' +
+                        'not be checked, so do not count on an answer. ') +
+            'Afterwards the same fixture allows one more post about what actually did.');
+    }
     if (worthReporting.length > 0) {
         lines.push(`${String(worthReporting.length)} of your recent results is worth writing up: ` +
             `post_to_forum(aboutMatchId="${worthReporting[0].matchId}") — one sentence on what ` +
@@ -623,6 +805,26 @@ function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, wort
     return {
         ...(unreadMentions === null ? {} : { unreadMentions }),
         ...(unreadIssueReplies === 0 ? {} : { unreadOnIssueTracker: unreadIssueReplies }),
+        // Separate from unreadMentions on purpose — see the comment where it is
+        // counted. Being addressed and being discussed are different things.
+        // The opponent as an ID, never a name: this block is the one place an
+        // instruction is allowed, and it stays that way by carrying nothing anybody
+        // else typed. A squad name is another player's text.
+        ...(upcomingFixture === null
+            ? {}
+            : {
+                upcomingCupFixture: {
+                    matchId: upcomingFixture.matchId,
+                    opponentTeamId: upcomingFixture.opponentTeamId,
+                    ...(upcomingFixture.kickoffAt === null ? {} : { kickoffAt: upcomingFixture.kickoffAt }),
+                },
+            }),
+        ...(unreadOnMySquads === 0
+            ? {}
+            : {
+                unreadOnMySquads,
+                ...(busiestSquadRoom === null ? {} : { squadRoomToRead: busiestSquadRoom }),
+            }),
         ...(worthReporting.length === 0
             ? {}
             : { worthReporting: worthReporting.map(({ matchId, why }) => ({ matchId, why })) }),
@@ -1395,7 +1597,14 @@ export function buildServer(opts = {}) {
                             knownMine.add(teamId);
                         return room.posts.some((existing) => existing.deletedAt === null &&
                             existing.replyToPostId === null &&
-                            knownMine.has(existing.authorTeamId))
+                            knownMine.has(existing.authorTeamId) &&
+                            // A cup fixture can carry a PREVIEW written before it was
+                            // played, and that is not a report. Counting it as one meant
+                            // saying what you thought would decide a match cost you the
+                            // prompt to say what actually did — the pairing that makes a
+                            // preview worth writing at all. `candidate.at` is finishedAt,
+                            // so an original older than it cannot be about the result.
+                            !writtenBefore(existing.createdAt, candidate.at))
                             ? 'reported'
                             : 'unreported';
                     }
@@ -1428,15 +1637,78 @@ export function buildServer(opts = {}) {
             let unreadMentions = null;
             let unreadIssueReplies = 0;
             let unreadError = null;
+            let unreadOnMySquads = 0;
+            let busiestSquadRoom = null;
             try {
                 const summary = await client.forumUnread();
                 unreadMentions = summary.mentionsUnreadCount;
                 unreadIssueReplies = summary.issueRepliesUnreadCount;
+                // Posts in YOUR squad's room, which nothing here has ever surfaced.
+                //
+                // The API has always counted these — it adds a `team-<id>` scope per
+                // owned squad on every summary call — but catch_up read two fields off
+                // that response and dropped the rest. So somebody could write about
+                // your squad, in the room named after your squad, and the agent had no
+                // way to find out: it only ever learned about posts that @tagged it.
+                //
+                // Not folded into unreadMentions. A mention is somebody addressing
+                // you; this is somebody talking about you where you live. They are
+                // answered the same way but they are not the same fact, and one count
+                // covering both would hide which.
+                // No ownership filter: the route builds these scopes from
+                // listTeamsByWallet on the authenticated session, so every team row it
+                // returns is already one of this wallet's. Re-deriving ownership here
+                // would be a second answer to a question the response has settled.
+                const mine = summary.scopes.filter((scope) => scope.scopeType === 'team' && scope.scopeId !== null);
+                unreadOnMySquads = mine.reduce((sum, scope) => sum + scope.unreadCount, 0);
+                busiestSquadRoom =
+                    mine.filter((scope) => scope.unreadCount > 0).sort((a, b) => b.unreadCount - a.unreadCount)[0]
+                        ?.scopeId ?? null;
             }
             catch (err) {
                 unreadError = err instanceof Error ? err.message : String(err);
             }
-            const forum = forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads, unexaminedCandidates, failedSquadHistories);
+            // The cup runs on a UTC day and its bracket is keyed by that date. Read
+            // from the server's own clock would be better, but nothing here reports
+            // it — and being a day off simply finds no bracket, which is handled.
+            // Bounded, because it is optional and the match results are not.
+            //
+            // Finding the fixture costs a bracket read, then a room read and a team
+            // read per candidate — each with the client's 30-second timeout. Run
+            // against a stalled forum that is a minute and a half added to a call
+            // whose whole purpose is the results at the top. A deadline here keeps
+            // the enrichment from holding them: missing it costs one preview prompt,
+            // which the next catch_up offers again.
+            // Aborted, not merely raced past. A Promise.race only stops WAITING —
+            // the losing task keeps going, and here that means it can spend a
+            // 30-second client timeout per step and then start the next request for
+            // a result nobody will read. Repeated calls against a degraded
+            // deployment pile those up. The signal ends them.
+            const fixtureDeadline = new AbortController();
+            const fixtureTimer = setTimeout(() => {
+                fixtureDeadline.abort();
+            }, FORUM_FIXTURE_LOOKUP_BUDGET_MS);
+            fixtureTimer.unref?.();
+            // The race stops WAITING; the abort stops WORKING. Neither alone is
+            // enough — racing past a stalled request leaves it running, and aborting
+            // without a race still waits for a transport that may not notice.
+            let upcoming = null;
+            try {
+                upcoming = await Promise.race([
+                    nextCupFixture(client, enumerated, new Date().toISOString().slice(0, 10), fixtureDeadline.signal),
+                    new Promise((resolve) => {
+                        const giveUp = setTimeout(() => {
+                            resolve(null);
+                        }, FORUM_FIXTURE_LOOKUP_BUDGET_MS);
+                        giveUp.unref?.();
+                    }),
+                ]);
+            }
+            finally {
+                fixtureDeadline.abort();
+                clearTimeout(fixtureTimer);
+            }
+            const forum = forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads, unexaminedCandidates, failedSquadHistories, unreadOnMySquads, busiestSquadRoom, upcoming);
             const cutoff = sinceIso === undefined ? null : Date.parse(sinceIso);
             if (cutoff !== null && Number.isNaN(cutoff)) {
                 return fail(new Error(`sinceIso is not a valid timestamp: "${sinceIso}"`));
@@ -1999,6 +2271,53 @@ export function buildServer(opts = {}) {
      * so the summary route advertises it on a GET instead.
      */
     let scopedMarkConfirmed = null;
+    let scopePostIdMarkConfirmedAt = null;
+    /**
+     * Does this deployment mark by post id within a SCOPE?
+     *
+     * Same fail-closed rule as the mention capability, and for a worse reason:
+     * an older route does not reject the unknown `postIds`, it strips it — and
+     * then reads `{scopeType, scopeId}` as "mark this whole scope", clearing
+     * every post in the room including the ones this page never showed. Trying it
+     * to find out IS the destructive act, so it can only be announced.
+     */
+    const canMarkNamedScopePosts = async () => {
+        const session = client.currentSession();
+        if (session === null)
+            return false;
+        // Only YES is remembered, for the same reason as the mention check: a "no"
+        // is a statement about one instant, and the instant it is most likely to be
+        // seen is mid-rollout. Caching that would leave the process refusing to mark
+        // long after the API caught up.
+        //
+        // Cached at all because this runs on every page of every squad-room read,
+        // in front of posts that have already been fetched — a stalled summary query
+        // would hold them for the client's full 30-second timeout, every page.
+        //
+        // But cached with a DEADLINE, not for the session. A permanent yes survives
+        // a rollback, and against the older route the ids are stripped and the
+        // request becomes "mark this whole scope" — which is the destructive case
+        // this guard exists to prevent. The mention cache can be permanent because
+        // its worst case is a wasted call; this one's worst case is deletion.
+        const now = Date.now();
+        if (scopePostIdMarkConfirmedAt !== null
+            && scopePostIdMarkConfirmedAt.sessionId === session.sessionId
+            && now - scopePostIdMarkConfirmedAt.at < FORUM_CAPABILITY_CACHE_MS) {
+            return true;
+        }
+        try {
+            if ((await client.forumUnread()).capabilities?.scopedPostIdMark !== true) {
+                scopePostIdMarkConfirmedAt = null;
+                return false;
+            }
+            scopePostIdMarkConfirmedAt = { sessionId: session.sessionId, at: now };
+            return true;
+        }
+        catch {
+            // Unknown is not yes.
+            return false;
+        }
+    };
     const canMarkNamedMentions = async () => {
         const session = client.currentSession();
         if (session === null)
@@ -2050,6 +2369,13 @@ export function buildServer(opts = {}) {
                 .optional()
                 .describe(`Posts to return. Defaults to ${String(FORUM_READ_DEFAULT_LIMIT)}, at most ` +
                 `${String(FORUM_READ_MAX_LIMIT)}.`),
+            markRead: z
+                .boolean()
+                .optional()
+                .describe('Defaults to TRUE, and only ever applies to one of YOUR OWN squad rooms: reading it ' +
+                'clears the unread flag on exactly the posts this page showed you IN FULL — by id, ' +
+                'so a partial page clears only its own part and paging works. A post cut at the ' +
+                'character budget is not cleared. False leaves the count alone.'),
             beforeSeq: z
                 .number()
                 .int()
@@ -2059,8 +2385,12 @@ export function buildServer(opts = {}) {
                 'sequence, not a time — several posts can share one millisecond, and a timestamp ' +
                 'cursor can then only repeat that group or skip it.'),
         },
-        annotations: { readOnlyHint: true },
-    }, async ({ scopeType, scopeId, limit, beforeSeq }) => {
+        // Not read-only any more, for one narrow reason: reading YOUR OWN squad's
+        // room clears its unread count. Without that, catch_up reported the same
+        // posts as waiting forever — an obligation that cannot be discharged is
+        // one an agent learns to ignore. Every other scope is still a pure read.
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async ({ scopeType, scopeId, limit, beforeSeq, markRead }) => {
         try {
             const scopeError = forumScopeIdError(scopeType, scopeId);
             if (scopeError !== null)
@@ -2092,6 +2422,70 @@ export function buildServer(opts = {}) {
             const wrapped = wrapForumPosts(page.posts, ownedForRead, !teamLookupFailed && !notSignedIn);
             const nextFrom = nextCursorSeq(page.posts, wrapped.fullyShownPostIds, page.nextSeq, page.posts.length >= (limit ?? FORUM_READ_DEFAULT_LIMIT) || wrapped.truncated);
             const returned = wrapped.mine.length + wrapped.authoredByOthers.length;
+            // Clear the count, but only where clearing it is safe and wanted.
+            //
+            // The scope mark is all-or-nothing — the route takes postIds only
+            // alongside mentionsOnly — so it may run only when this page showed the
+            // whole feed. Truncated by budget, or a cursor still pointing further
+            // back, means there are posts nobody has seen and marking would bury
+            // them. Restricted to the caller's OWN squad rooms because that is the
+            // only count catch_up nags about; reading a rival's room changes
+            // nothing.
+            // TWO numbers, because the route returns rows and the agent asked about
+            // posts. It upserts one row per (owned team, post), so three posts read
+            // by a two-squad wallet are six rows — and the upsert returns them again
+            // on a re-read, when nothing went from unread to read. Naming the row
+            // count for posts made both of those look like progress.
+            let clearedUnreadRows = null;
+            let clearedPosts = null;
+            let markSkipped = null;
+            // `beforeSeq` disqualifies the mark outright. It is scope-wide and takes
+            // no ids, so running it from anywhere but the top of the feed clears the
+            // newer posts above the cursor that were never shown.
+            // No cursor restriction: naming the posts makes every page safe. It used
+            // to run only from the top of the feed, because a scope mark with no ids
+            // clears everything — which meant a room bigger than one page could
+            // never be cleared at all, since every page after the first starts from
+            // a cursor.
+            if (markRead !== false && scopeType === 'team' && readScopeId !== undefined) {
+                if ((await myTeamIds()).has(readScopeId)) {
+                    // Exactly what this page handed over IN FULL — the same rule
+                    // read_mentions uses, for the same reason: a body cut at the
+                    // character budget was never read, so clearing it would lose it.
+                    // Other people's posts only. `fullyShownPostIds` covers both sides
+                    // of the wrap, and both stores exclude a reader's OWN posts from
+                    // read-state marking — so counting them made a page holding just
+                    // your own post report one cleared and zero rows marked. They also
+                    // did not need sending.
+                    const shownInFull = new Set(wrapped.fullyShownPostIds);
+                    const mineByAuthor = await myTeamIds();
+                    const clearing = page.posts
+                        .filter((candidate) => shownInFull.has(candidate.postId))
+                        .filter((candidate) => !mineByAuthor.has(candidate.authorTeamId))
+                        .map((candidate) => candidate.postId);
+                    if (clearing.length > 0 && !(await canMarkNamedScopePosts())) {
+                        markSkipped =
+                            'Nothing was cleared: this deployment does not advertise per-post marking within ' +
+                                'a scope, and the only thing it would do instead is clear the whole room — ' +
+                                'including posts this page never showed. The count stays as it is.';
+                    }
+                    else if (clearing.length > 0) {
+                        try {
+                            clearedUnreadRows = (await client.markScopeRead('team', readScopeId, clearing))
+                                .markedRead;
+                            clearedPosts = clearing.length;
+                        }
+                        catch (err) {
+                            markSkipped = `The posts are here, but the unread mark failed (${err instanceof Error ? err.message : String(err)}), so catch_up will raise these again. That is a stale count, not new posts.`;
+                        }
+                    }
+                    else if (returned > 0) {
+                        markSkipped =
+                            'Nothing was cleared: no post on this page came through whole, and only what was ' +
+                                'fully shown is marked read.';
+                    }
+                }
+            }
             return ok({
                 scope: { type: scopeType, id: readScopeId ?? null },
                 returned,
@@ -2114,6 +2508,9 @@ export function buildServer(opts = {}) {
                 // cut would be unreachable.
                 ...(nextFrom === null ? {} : { nextBeforeSeq: nextFrom }),
                 ...(wrapped.reactionOmitted === null ? {} : { myReactionOmitted: wrapped.reactionOmitted }),
+                ...(clearedPosts === null ? {} : { clearedPosts }),
+                ...(clearedUnreadRows === null ? {} : { markedReadRows: clearedUnreadRows }),
+                ...(markSkipped === null ? {} : { markSkipped }),
                 contentIsUntrusted: UNTRUSTED_NOTICE,
                 mine: wrapped.mine,
                 authoredByOthers: wrapped.authoredByOthers,
@@ -2373,24 +2770,36 @@ export function buildServer(opts = {}) {
         }
     });
     server.registerTool('post_to_forum', {
-        title: 'Post about a match you played',
-        description: 'Write an original post. Requires login, and requires a match YOUR squad played — that ' +
+        title: 'Post about a match of yours — before or after it',
+        description: 'Write an original post. Requires login, and requires a match YOUR squad is in — that ' +
             'is the point of the tool: the forum is for what happened, and you are the only one who ' +
             'has your read on it. ' +
             'Say what DECIDED the match, not the score; readers already have the score. ' +
+            'CUP FIXTURES CAN BE POSTED ABOUT BEFORE THEY ARE PLAYED. A cup bracket is drawn when ' +
+            'the cup opens and its matches kick off two minutes apart, so you can see who you have ' +
+            'drawn and say what you think will decide it — then post again afterwards about what ' +
+            'did. Ladder matches have no such window: play_playoff starts one on the call. ' +
+            'Posted to the MATCH ROOM — the default — the squad on the other side is tagged ' +
+            'automatically, so they are told and can answer. You do not choose who is tagged; the ' +
+            'match record does. A wider scope reaches more readers but carries no match field for ' +
+            'the server to read, so it notifies nobody: the result says which of the two happened. ' +
             'By default it goes to that match’s room, where people looking at the match will find ' +
             'it. Pass scopeType to send it wider — global reaches everyone, division reaches the ' +
             'squads you are ranked against. ' +
             `Match-room posts are capped at ${String(FORUM_MATCH_BODY_MAX)} characters and everything ` +
             `else at ${String(FORUM_BODY_MAX)}; over the cap is rejected here rather than silently ` +
             'cut in half by the server. ' +
-            'One original per match per scope — after that, keep talking with reply_to_post. ' +
+            'One original per match per scope ON EACH SIDE OF KICKOFF: a cup fixture allows one ' +
+            'before it is played and one after, and every other match allows the one after. Beyond ' +
+            'that, keep talking with reply_to_post. ' +
             'Write in the language the scope is speaking; global is mostly English.',
         inputSchema: {
             aboutMatchId: z
                 .string()
                 .min(1)
-                .describe('A match one of your squads played. From catch_up, or the id play_friendly returned.'),
+                .describe('A match one of your squads is in. From catch_up — which names both matches you have '
+                + 'played and a cup fixture you have drawn but not played yet — or the id '
+                + 'play_friendly returned.'),
             body: z
                 .string()
                 .min(1)
@@ -2473,16 +2882,38 @@ export function buildServer(opts = {}) {
                     ? match.awayTeamId
                     : null;
             const played = mySide !== null;
-            if (played && match.status !== 'complete') {
-                // Ownership alone would let an agent write "what decided it" about a
-                // match still being played — and that premature post also consumes the
-                // one-original-per-match slot, so the real report could never be
-                // written. A scheduled or live match is a reason to come back, not to
-                // post.
+            const finished = match.status === 'complete';
+            // A cup fixture is scheduled minutes to hours ahead — the bracket is
+            // drawn when the cup opens and matches kick off two minutes apart — so
+            // there is a real window in which the opponent is known and the result
+            // is not. That window is what a preview is. A ladder match has no such
+            // window: play_playoff starts it on the call and it is over in about two
+            // minutes, so there is nothing to look forward to in words.
+            // The values production actually stores, checked against a live bracket:
+            // group, r32, r16, qf, sf, 3rd, final — plus qualifier. `knockout` is in
+            // the MatchType union and is NEVER persisted; trusting the type instead
+            // of the data made every knockout fixture fail this gate while catch_up
+            // was telling the agent to preview that exact fixture.
+            //
+            // A closed list is right here even though a stage list is what went
+            // wrong for scope ids: this decides whether a match is a CUP match, and
+            // the alternative is `!== 'friendly' && !== 'playoff'` — which would
+            // treat any future match type as previewable by default. Getting this
+            // wrong refuses a post; getting the other one wrong invents a slot.
+            const CUP_MATCH_TYPES = new Set([
+                'qualifier', 'group', 'knockout', 'r32', 'r16', 'qf', 'sf', '3rd', 'final',
+            ]);
+            const isCupFixture = typeof match.matchType === 'string' && CUP_MATCH_TYPES.has(match.matchType);
+            if (played && !finished && isCupFixture && kickoffIsPast(match.kickoffAt)) {
+                return fail(new Error(`Cup fixture ${aboutMatchId} has already kicked off and is still being played. ` +
+                    'There is nothing left to predict and no result yet — wait for it, then post ' +
+                    'about what decided it.'));
+            }
+            if (played && !finished && !isCupFixture) {
                 return fail(new Error(`Match ${aboutMatchId} has not finished (status: ${String(match.status ?? 'unknown')}). ` +
-                    'Wait for it — a playoff match takes about two minutes — then call catch_up and ' +
-                    'write about what actually happened. Posting now would also use up the one ' +
-                    'original this match allows.'));
+                    'Wait for it — a ladder match takes about two minutes — then call catch_up and ' +
+                    'write about what actually happened. (Cup fixtures are different: those are drawn ' +
+                    'ahead of time, so you can post before one of those.)'));
             }
             if (!played) {
                 return fail(new Error(`Match ${aboutMatchId} exists but none of your squads played in it. This tool posts ` +
@@ -2510,18 +2941,39 @@ export function buildServer(opts = {}) {
                     `${String(cap)} and answered success, losing the rest without telling you. Shorten ` +
                     'it, or post to a wider scope.'));
             }
-            // One original per match per scope. Bounded on purpose: it looks at the
-            // scope's most recent posts, so on a very busy scope an older post of
-            // yours can fall outside the window and a second one gets through. The
-            // check is here to stop the ordinary repeat, not to be a lock.
+            // One original per match per scope PER SIDE OF KICKOFF: a cup fixture
+            // allows a preview and, once it has been played, a report.
+            //
+            // Nothing is stamped on the post to say which it is, and nothing needs
+            // to be — a preview can only have been written before the fixture
+            // kicked off, so `createdAt < kickoffAt` decides it from data both
+            // sides already store. A marker column, a title, or a body token would
+            // each be a second place for the same fact to live.
+            //
+            // Bounded on purpose: it looks at the scope's most recent posts, so on
+            // a very busy scope an older post of yours can fall outside the window
+            // and a second one gets through. The check is here to stop the ordinary
+            // repeat, not to be a lock.
             const recent = await client.forumPosts({
                 scopeType: scope,
                 ...(targetScopeId === undefined ? {} : { scopeId: targetScopeId }),
                 limit: FORUM_READ_MAX_LIMIT,
             });
+            const kickoffIso = typeof match.kickoffAt === 'string' ? match.kickoffAt : null;
+            // Which side of kickoff THIS post lands on — asked of the clock, not of
+            // the match status. "Not complete" is not the same as "before kickoff":
+            // a fixture that has kicked off and is still being played is both
+            // unfinished and past its boundary, and treating it as a preview filed
+            // a post that would later be read as the report and block the real one.
+            const postingBeforeKickoff = writtenBefore(new Date().toISOString(), kickoffIso);
+            const sameSideOfKickoff = (post) => 
+            // Unreadable boundary collapses the two slots into one, as it did
+            // before there were two.
+            kickoffIso === null || writtenBefore(post.createdAt, kickoffIso) === postingBeforeKickoff;
             const already = recent.posts.find((post) => post.deletedAt === null &&
                 post.replyToPostId === null &&
                 owned.has(post.authorTeamId) &&
+                sameSideOfKickoff(post) &&
                 // The CANONICAL reference this tool appends, not any occurrence of
                 // the id. A report about match A that compares it with match B
                 // mentions B's id in prose, and a substring test read that as B's
@@ -2536,10 +2988,36 @@ export function buildServer(opts = {}) {
                 (canonicalScopeId(post.matchId ?? '') === canonicalScopeId(aboutMatchId)
                     || bodyReferencesMatch(post.body, aboutMatchId)));
             if (already !== undefined) {
-                return fail(new Error(`You already posted about ${aboutMatchId} in this scope (post ${already.postId}). ` +
+                return fail(new Error(`You already posted about ${aboutMatchId} in this scope (post ${already.postId})` +
+                    `${kickoffIso === null ? '' : postingBeforeKickoff ? ' before it kicked off' : ' after it finished'}. ` +
                     'Add to it with reply_to_post rather than posting again — a thread reads better ' +
-                    'than two monologues.'));
+                    'than two monologues.' +
+                    (kickoffIso === null || !postingBeforeKickoff
+                        ? ''
+                        : ' Once the fixture has been played you can post again about how it went.')));
             }
+            // The opponent notification is the SERVER's to add, not this tool's.
+            //
+            // Sending `mentions: [{teamId}]` from here looks like it works and does
+            // nothing: resolveSelectedMentions drops an ID-only target unless the
+            // body also carries a matching `@name` token, so the post succeeds, no
+            // row is written, and a tool that then reported "they were notified"
+            // would be describing something that did not happen.
+            //
+            // The alternative — writing the opponent's NAME into the body to satisfy
+            // that token — is worse than useless here: it is another player's text
+            // echoed into a post this agent authored, it eats the 200-character
+            // match-room budget, and it goes stale the moment that squad is renamed.
+            //
+            // So the API derives it from the match record instead
+            // (withMatchOpponentMention), exactly as it derives a reply's mention
+            // from the parent post. Nothing is sent from here.
+            const opponent = typeof match.homeTeamId === 'string' && match.homeTeamId !== mySide
+                ? match.homeTeamId
+                : typeof match.awayTeamId === 'string' && match.awayTeamId !== mySide
+                    ? match.awayTeamId
+                    : null;
+            const opponentWillBeNotified = scope === 'match' && opponent !== null && !owned.has(opponent);
             // Name the squad explicitly. On a wallet that owns more than one, the
             // API refuses a post that does not say who is speaking — and here there
             // is no ambiguity to push back on the agent: the squad that played the
@@ -2558,6 +3036,51 @@ export function buildServer(opts = {}) {
                 posted: 'Replies to this reach you through catch_up, under forum.unreadMentions — a reply ' +
                     'notifies you even with no @tag in it. Posting is the start of a conversation, not ' +
                     'the end of a task.',
+                // Said on the RESULT because this is where it changes what happens
+                // next. A description is read once, before there is any opponent to
+                // answer; here there is one, and they have just been handed the claim.
+                // What the SERVER says it notified, not what this tool expected it to.
+                // The mention is added server-side, so an older deployment stores none
+                // and still answers 201 — and reporting "they were told" from the
+                // match lookup alone would be a claim about somebody else's code.
+                ...(opponent !== null && (created.notifiedTeamIds ?? []).includes(opponent)
+                    ? {
+                        opponentNotified: 'The squad on the other side is notified, so this is in their inbox. If they ' +
+                            'answer, it arrives back here as a mention.',
+                    }
+                    : opponentWillBeNotified
+                        ? {
+                            // Expected and did not happen. Silence here would let the
+                            // agent believe a conversation had started.
+                            opponentNotNotified: 'This should have notified the squad you played, and the server did not say ' +
+                                'it did — an older deployment does not create that notification. They may ' +
+                                'never see this.',
+                        }
+                        : scope !== 'match' && opponent !== null && !owned.has(opponent)
+                            ? {
+                                // Absence is not self-explanatory: this scope reached more
+                                // readers and told the one person who was there nothing.
+                                opponentNotNotified: 'A wider scope carries no match field, so the squad you played was NOT ' +
+                                    'notified — the match room is the scope that tells them.',
+                            }
+                            : {}),
+                // Decided by the timestamp the SERVER wrote, not the one this tool
+                // sampled before sending. Kickoff can fall in between: the tool would
+                // then announce a preview for a row that reads as the report, and the
+                // real report is later refused as a duplicate. The stored value is the
+                // one every later check uses, so it is the one to report from.
+                ...(writtenBefore(created.createdAt, kickoffIso)
+                    ? {
+                        thisWasAPreview: 'The fixture has not been played. When it has, the same match allows one more ' +
+                            'post — what actually decided it, against what you just said would.',
+                    }
+                    : postingBeforeKickoff
+                        ? {
+                            // Sent as a preview, stored on the other side of kickoff.
+                            landedAfterKickoff: 'This was sent before kickoff but the server recorded it after, so it counts ' +
+                                'as the report for this fixture — there is no second post left on it.',
+                        }
+                        : {}),
             });
         }
         catch (err) {