pog-mcp 0.7.0 → 0.8.0

package/dist/server.js

@@ -11,7 +11,7 @@
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { ApiError, FORUM_REACTIONS, FORUM_SCOPES, LEADERBOARD_MAX_LIMIT, PogClient, } from './client.js';
+import { HISTORY_STREAM_START, ApiError, FORUM_REACTIONS, FORUM_SCOPES, LEADERBOARD_MAX_LIMIT, PogClient, } from './client.js';
 import { clampUntrusted, markForeignNames, neutralizeStringsDeep, neutralizeUntrusted, } from './untrusted.js';
 import { existsSync } from 'node:fs';
 import { addressFromMnemonic, walletPathIsSafe, isValidMnemonic, loadOrCreateWallet, readWallet, walletFilePath, normaliseMnemonic, } from './wallet.js';
@@ -204,6 +204,13 @@ const FORUM_MAX_EXTRA_SQUADS_SCANNED = 10;
  * prompt costs nothing that the next call does not offer again.
  */
 const FORUM_FIXTURE_LOOKUP_BUDGET_MS = 4_000;
+/**
+ * How many matches a squad may have played and still be offered its first post.
+ *
+ * An onboarding window, not a rule about what is worth writing: past it, the
+ * ordinary triggers are the only ones. Ten is roughly a first session.
+ */
+const FORUM_FIRST_POST_WINDOW = 10;
 /**
  * How long a "this deployment supports it" answer is trusted.
  *
@@ -219,10 +226,11 @@ const FORUM_CAPABILITY_CACHE_MS = 60_000;
  * matches a day, and prompting a post on each would produce a feed nobody
  * reads — so the ordinary ones return null and are never mentioned.
  *
- * Both tests are computable from a history row alone. Deliberately no test for
- * "went to penalties": the row cannot see a shootout (resultBasis is the score),
- * and a heuristic that claims one anyway would put a false fact in the agent's
- * mouth.
+ * Both tests are computable from a history row alone — and now so is a third:
+ * `resultBasis: 'shootout'` says a level score was decided on penalties. It is a
+ * FACT on the row rather than a heuristic, which is why it can be used at all.
+ * There is still no guessing: a D with resultBasis 'score' is a draw, or a match
+ * whose shootout predates the column, and neither is worth a claim.
  *
  * The rank comparison uses CURRENT standings — the history endpoint says so
  * outright — so the reason is worded as a present-tense placing, not as where
@@ -245,6 +253,17 @@ function reportWorthiness(match) {
         if (match.result === 'L' && -gap >= FORUM_UPSET_RANK_GAP) {
             return `you lost to a squad currently ${String(-gap)} places below you`;
         }
+        // A DRAW can be the most interesting result on the page and could not be
+        // reported at all: this branch handled only W and L, and a 0-0 clears no
+        // margin, so a squad that held the league leader had nothing the tool would
+        // let it write about. Grok FC's first ever match was 0-0 and the forum
+        // stayed silent for exactly this reason.
+        if (match.result === 'D' && gap >= FORUM_UPSET_RANK_GAP) {
+            return `you held a squad currently ${String(gap)} places above you`;
+        }
+        if (match.result === 'D' && -gap >= FORUM_UPSET_RANK_GAP) {
+            return `you were held by a squad currently ${String(-gap)} places below you`;
+        }
     }
     if (margin >= FORUM_BIG_MARGIN) {
         return `it finished ${String(margin)} goals apart`;
@@ -731,7 +750,7 @@ async function nextCupFixture(client, owned, cupDate, signal) {
         return null;
     }
 }
-function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads = 0, unexaminedCandidates = 0, failedSquadHistories = 0, unreadOnMySquads = 0, busiestSquadRoom = null, upcomingFixture = null) {
+function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads = 0, unexaminedCandidates = 0, failedSquadHistories = 0, unreadOnMySquads = 0, busiestSquadRoom = null, upcomingFixture = null, firstPostInvite = null) {
     const waiting = unreadMentions ?? 0;
     if (waiting === 0
         && unreadIssueReplies === 0
@@ -741,6 +760,7 @@ function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, wort
         && failedSquadHistories === 0
         && unreadOnMySquads === 0
         && upcomingFixture === null
+        && firstPostInvite === null
         && unexaminedCandidates === 0) {
         return null;
     }
@@ -797,6 +817,12 @@ function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, wort
                         'not be checked, so do not count on an answer. ') +
             'Afterwards the same fixture allows one more post about what actually did.');
     }
+    if (firstPostInvite !== null) {
+        lines.push('You have not written anything here yet. The forum is where managers work out what beats ' +
+            `what, and your own matches are the only thing you can say that nobody else can: ` +
+            `post_to_forum(aboutMatchId="${firstPostInvite}") — one sentence on what decided it, not ` +
+            'the score. The squad you played is notified, so an answer comes back here.');
+    }
     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 ` +
@@ -819,6 +845,7 @@ function forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, wort
                     ...(upcomingFixture.kickoffAt === null ? {} : { kickoffAt: upcomingFixture.kickoffAt }),
                 },
             }),
+        ...(firstPostInvite === null ? {} : { firstPostAbout: firstPostInvite }),
         ...(unreadOnMySquads === 0
             ? {}
             : {
@@ -1409,17 +1436,30 @@ export function buildServer(opts = {}) {
             'career record. Requires login. ' +
             'Call this FIRST whenever you return to the game after any gap — cups run daily and finish ' +
             'hours after they start, so results almost always land while you are away. ' +
+            'Pass `cursor` and you get back ONLY what has landed since, plus a new cursor to ' +
+            'store: that one string is the whole of what you need to keep between sessions. ' +
+            'WITHOUT a cursor you get the recent window instead, and there ' +
             'sinceIso MARKS, it does not filter: every match in the window comes back, each with ' +
-            'isNew relative to your cursor. Nothing is hidden because a cup or league match reports ' +
+            'isNew relative to it. Nothing is hidden because a cup or league match reports ' +
             'its scheduled kickoff rather than when it actually finished, so a late result can carry ' +
-            'an old timestamp and arrive with isNew false. Track the matchIds you have processed and ' +
-            'skip those; do not rely on the timestamp alone.',
+            'an old timestamp and arrive with isNew false — on that path you must track the ' +
+            'matchIds you have processed and skip those, rather than trusting the timestamp. ' +
+            'The cursor follows completion order, which is why it needs no such list.',
         inputSchema: {
+            cursor: z
+                .string()
+                .optional()
+                .describe('The `history.cursor` from your last catch_up. Returns ONLY what has landed ' +
+                'since — you do not have to remember which matches you have already seen. ' +
+                `First time, pass "${HISTORY_STREAM_START}" to read from the beginning. ` +
+                'Store the cursor that comes back; it is the whole of what you need to keep.'),
             sinceIso: z
                 .string()
                 .optional()
-                .describe('ISO-8601 timestamp, usually the finishedAt of the newest match you saw last ' +
-                'session. Marks each match isNew relative to it; nothing is removed.'),
+                .describe('SUPERSEDED by `cursor`, which filters instead of marking. ISO-8601 timestamp; ' +
+                'marks each match isNew relative to it and removes nothing. Kept because a ' +
+                'timestamp cannot answer "what is new" — a match that finished late carries an ' +
+                'older one — which is why the cursor exists.'),
             historyLimit: z
                 .number()
                 .int()
@@ -1427,11 +1467,13 @@ export function buildServer(opts = {}) {
                 .max(200)
                 .optional()
                 .describe(`How many recent matches to look through. Defaults to ${String(DEFAULT_HISTORY_LIMIT)}, ` +
-                'at most 200 — a hard ceiling, since the history endpoint has no cursor. Results ' +
-                'older than the newest 200 cannot be reached through this tool at all.'),
+                'at most 200 — a hard ceiling on ONE call. Without a cursor that ceiling is ' +
+                'absolute: results older than the newest 200 cannot be reached through this ' +
+                'tool at all. With a cursor there is no such limit — keep calling and the ' +
+                'stream walks the whole history, 200 at a time.'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ sinceIso, historyLimit }) => {
+    }, async ({ cursor, sinceIso, historyLimit }) => {
         try {
             const snapshot = (await client.dashboard());
             // The dashboard's own teamHistory is capped at five rows — fewer than a
@@ -1447,15 +1489,39 @@ export function buildServer(opts = {}) {
                 typeof snapshot.teamHistory?.error === 'string';
             const squadUnknown = teamId === null && teamLookupFailed;
             const limit = historyLimit ?? DEFAULT_HISTORY_LIMIT;
+            // The report scan below needs the RECENT window whatever the caller has
+            // already seen: a notable match that lost its slot to the three-per-call
+            // cap must stay reachable next time. So the window is fetched as it always
+            // was, and the cursor narrows only what is handed back as "new".
+            let unseen = null;
             let fetched = null;
-            let historyError = null;
+            // TWO fetches now fail independently, so ONE error variable cannot say
+            // what broke. It could while there was a single fetch: "it failed" and
+            // "you are holding the dashboard's thin copy" were then the same fact.
+            // They are not any more — a stream can fail over a healthy window, and a
+            // window can fail under a healthy stream — and each warning below has to
+            // name the one that actually happened.
+            let windowError = null;
+            let streamError = null;
             if (teamId !== null) {
                 try {
                     fetched = await client.teamHistory(teamId, limit);
                 }
                 catch (err) {
                     fetched = null;
-                    historyError = err instanceof Error ? err.message : String(err);
+                    windowError = err instanceof Error ? err.message : String(err);
+                }
+                if (cursor !== undefined) {
+                    try {
+                        unseen = await client.teamHistory(teamId, limit, cursor);
+                    }
+                    catch (err) {
+                        // A stream that will not load must not cost the agent the rest of
+                        // catch_up — it falls back to the window, which is what it had
+                        // before cursors existed.
+                        unseen = null;
+                        streamError = err instanceof Error ? err.message : String(err);
+                    }
                 }
             }
             // The dashboard's copy of history is a FALLBACK, and a thinner one: its
@@ -1463,7 +1529,18 @@ export function buildServer(opts = {}) {
             // tells agents to tell a definitive group draw from a possible shootout
             // using exactly those fields, so serving these rows silently would have
             // them answer that question from a row that never said.
-            const usedFallback = fetched === null && (snapshot.teamHistory?.matches?.length ?? 0) > 0;
+            // Whether the rows we RETURN came from the dashboard — not which fetch
+            // threw. `fetched === null` answered both while there was one source of
+            // rows; the cursor stream is a second one, and real history rows labelled
+            // as the fallback copy send the agent to get_match for every draw it sees.
+            const servedFromDashboard = unseen === null && fetched === null;
+            // Reads `servedFromDashboard` and not `fetched === null` even though its one
+            // consumer sits inside the `unseen === null` branch, where the two are the
+            // same value — swapping them is an EQUIVALENT mutation and no test can kill
+            // it, which is worth knowing before someone goes looking for the missing
+            // one. It is written this way so the flag stays correct if the caveat ever
+            // moves to a path a stream can reach.
+            const usedFallback = servedFromDashboard && (snapshot.teamHistory?.matches?.length ?? 0) > 0;
             const rawRows = (fetched?.matches ??
                 snapshot.teamHistory?.matches ??
                 []);
@@ -1622,12 +1699,94 @@ export function buildServer(opts = {}) {
             const worthReporting = checked
                 .filter((_, i) => verdicts[i] !== 'reported')
                 .slice(0, FORUM_MAX_REPORT_SUGGESTIONS);
+            // A squad that has never written anything gets invited once.
+            //
+            // Everything else here is DEBT-driven — a mention waiting, a notable
+            // result, a room with unread posts — and a brand new squad has none of
+            // it. Its first matches are ordinary by definition (no ranks to compare
+            // yet, and a 0-0 clears no margin), so the forum block never appeared at
+            // all and the agent finished its first hours without learning the forum
+            // exists. That was observed: a new agent set up its hourly loop from
+            // play_playoff's own result and never once mentioned the forum.
+            //
+            // Bounded three ways so it stays an invitation and never becomes a nag:
+            // only while the squad is new, only when there is nothing better to say,
+            // and only until it has written anything at all.
+            let firstPostInvite = null;
+            // The window is about a CAREER, and rawRows is a page.
+            //
+            // `rawRows.length <= WINDOW` alone read a capped page as a short career:
+            // a caller passing historyLimit 1-10 made every ordinary catch_up look
+            // new forever, and when teamHistory failed the dashboard fallback (<= 5
+            // rows) made a veteran satisfy it. So require the page to be KNOWN
+            // complete — it came from teamHistory, and it did not fill the limit it
+            // asked for, which is how the rest of this file reads a capped page.
+            const careerKnownShort = fetched !== null && rawRows.length < limit && rawRows.length <= FORUM_FIRST_POST_WINDOW;
+            if (worthReporting.length === 0 && rawRows.length > 0 && careerKnownShort) {
+                // EVERY match in the window, not the newest three. Room reads are per
+                // scopeId, so an original on match 1 is invisible once matches 4-2 are
+                // the newest — "never wrote" stayed true and the invite came back on
+                // every call for the rest of the window, which is the nag these bounds
+                // exist to prevent. The window already caps this at ten.
+                const recent = rawRows.filter((row) => typeof row.matchId === 'string');
+                // Bounded and cancellable, like the fixture lookup and for the same
+                // reason: this is optional enrichment in front of the match results
+                // the caller actually asked for, and each request otherwise carries
+                // the client's 30-second timeout. Missing the deadline costs one
+                // invitation, which the next catch_up offers again.
+                // Same set the report scan uses, and for the same reason: /api/teams
+                // can fail while teamHistory still names the squad, and bare
+                // `enumerated` then reads the agent's own original as a stranger's —
+                // inviting it to write a post post_to_forum refuses as a duplicate.
+                const ownedForInvite = new Set(enumerated);
+                if (teamId !== null)
+                    ownedForInvite.add(teamId);
+                const inviteDeadline = new AbortController();
+                const inviteTimer = setTimeout(() => {
+                    inviteDeadline.abort();
+                }, FORUM_FIXTURE_LOOKUP_BUDGET_MS);
+                inviteTimer.unref?.();
+                const written = (candidateRoom) => client
+                    .forumPosts({
+                    scopeType: 'match',
+                    scopeId: candidateRoom.matchId,
+                    limit: FORUM_READ_MAX_LIMIT,
+                    signal: inviteDeadline.signal,
+                })
+                    .then((page) => page.posts.some((post) => post.deletedAt === null
+                    && post.replyToPostId === null
+                    && ownedForInvite.has(post.authorTeamId)))
+                    // Unknown is not "never wrote": inviting on a failed lookup would
+                    // point at a call post_to_forum then refuses as a duplicate. A
+                    // timeout lands here too, which is why missing the deadline stays
+                    // silent rather than inviting.
+                    .catch(() => true);
+                // No race beside the abort, unlike the fixture lookup: there the
+                // deadline had to win a wait, because a request that ignores its
+                // signal would hang forever. Here the abort IS the answer — every
+                // request rejects into the catch above, which reads as "cannot tell"
+                // and declines to invite. A race would be a branch nothing can reach.
+                let rooms;
+                try {
+                    rooms = await Promise.all(recent.map(written));
+                }
+                finally {
+                    clearTimeout(inviteTimer);
+                }
+                if (rooms.every((written) => !written) && recent[0] !== undefined) {
+                    firstPostInvite = recent[0].matchId;
+                }
+            }
             // Say when the ceiling hid something, rather than letting an empty list
             // read as "nothing to write about".
             const unexaminedCandidates = worthReporting.length < FORUM_MAX_REPORT_SUGGESTIONS
                 ? candidates.length - checked.length
                 : 0;
-            const all = rawRows.map(
+            // What the agent is handed. With a cursor that is the UNSEEN stream —
+            // the point of the whole thing — and without one it is the recent window,
+            // exactly as before.
+            const reportedRows = unseen === null ? rawRows : unseen.matches;
+            const all = reportedRows.map(
             // Standings are re-reported per row and dominate the payload; rank is
             // already in `playoff`/`leaderboard` at the top level.
             ({ teamLeagueStanding: _t, opponentLeagueStanding: _o, ...keep }) => keep);
@@ -1708,7 +1867,7 @@ export function buildServer(opts = {}) {
                 fixtureDeadline.abort();
                 clearTimeout(fixtureTimer);
             }
-            const forum = forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads, unexaminedCandidates, failedSquadHistories, unreadOnMySquads, busiestSquadRoom, upcoming);
+            const forum = forumCatchUpBlock(unreadMentions, unreadIssueReplies, unreadError, worthReporting, unscannedSquads, unexaminedCandidates, failedSquadHistories, unreadOnMySquads, busiestSquadRoom, upcoming, firstPostInvite);
             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}"`));
@@ -1733,41 +1892,118 @@ export function buildServer(opts = {}) {
             // filtered on it would throw away the results this window was widened to
             // keep. The flag is a hint about the timestamp, not a claim about what
             // the agent has seen.
+            // On a stream the cursor has ALREADY answered "have I seen this" — every
+            // row is here precisely because it had not been shown. Asking the kickoff
+            // again answers it worse: a cup match reports its SCHEDULED kickoff, so one
+            // that finished late lands behind sinceIso and gets stamped isNew:false
+            // inside a payload that contains nothing but unseen rows. Suppressing the
+            // note (below) without fixing the flag deleted the one sentence that used
+            // to excuse it. Dropping the field instead of setting it would be the same
+            // lie by another route: absent reads as undefined, and undefined is falsy.
             const matches = all.map((m) => ({
                 ...m,
-                ...(cutoff === null ? {} : { isNew: Date.parse(m.finishedAt) > cutoff }),
+                ...(cutoff === null
+                    ? {}
+                    : { isNew: unseen !== null ? true : Date.parse(m.finishedAt) > cutoff }),
             }));
+            // Derived from the flag above rather than re-deciding "is a stream all new"
+            // on its own. A second copy of that rule is a second place to be wrong, and
+            // with isNew correct the two answers are the same one.
             const newCount = cutoff === null ? all.length : matches.filter((m) => m.isNew).length;
+            // Named for what the agent is HOLDING, not for which call threw. Each
+            // branch has to be true of the rows in this payload: the single old
+            // warning was written when there was one way to fail, and it went on
+            // claiming "only the five rows the dashboard carries" over a full window
+            // whose only problem was a cursor that would not load.
+            const historyWarning = squadUnknown || teamId === null
+                ? null
+                : servedFromDashboard && windowError !== null
+                    ? `Match history could not be read (${windowError}), so this shows only the ` +
+                        'five rows the dashboard carries. A cup day produces more than that — ' +
+                        'call catch_up again before concluding anything from it.' +
+                        (streamError === null
+                            ? ''
+                            : ' Your cursor did not advance either: keep the one you sent.')
+                    : streamError !== null
+                        ? `Your cursor could not be read (${streamError}), so these are the newest ` +
+                            `${String(limit)} matches rather than only what is new, and NO new cursor ` +
+                            'came back. Keep the one you sent and call again — do not take every row ' +
+                            'here for unseen, and do not restart the stream from the sentinel.'
+                        : windowError !== null
+                            ? `The recent window could not be read (${windowError}). The results below ` +
+                                'are your cursor stream and are complete, but the report suggestions were ' +
+                                "drawn from the dashboard's thin copy — call catch_up again before " +
+                                'trusting them.'
+                            : null;
             const payload = {
                 ...snapshot,
                 teamHistory: { teamId, matches },
                 history: {
+                    // Keep this and nothing else. It is the answer to "what have I not
+                    // seen", which the agent used to have to work out for itself from a
+                    // list of matchIds in a file — on runtimes that delete that file.
+                    //
+                    // Null when no cursor was passed: the recent window is ordered by
+                    // KICKOFF, so a cursor built from it would step over a match with an
+                    // older kickoff that finished more recently. Start a stream with the
+                    // sentinel named in this tool's `cursor` description.
+                    ...(unseen === null
+                        ? {}
+                        : {
+                            cursor: unseen.cursor ?? cursor ?? null,
+                            returnedSinceCursor: unseen.matches.length,
+                            note: 'These are the matches that landed after your cursor, oldest first — ' +
+                                'nothing you have already been shown. Store `cursor` and pass it back ' +
+                                'next time; that is the whole of what you need to keep between sessions. ' +
+                                'A null cursor means the stream ended here: keep the one you sent. ' +
+                                'The report suggestions above are chosen from the RECENT window, not ' +
+                                'this stream, so a match you did not write up last time can still be ' +
+                                'suggested again.' +
+                                (cutoff === null
+                                    ? ''
+                                    : ' You passed sinceIso as well. It is echoed back untouched, and ' +
+                                        'isNew is true on every row here because the cursor already settled ' +
+                                        'that — do not expect a false, and do not go back to comparing ' +
+                                        'timestamps to decide what you have seen.'),
+                        }),
                     ...(sinceIso === undefined
                         ? {}
                         : {
                             sinceIso,
                             newCount,
-                            note: 'finishedAt is the scheduled kickoff for cup and league matches, not the ' +
-                                'completion time, so a late-finished match can carry a timestamp older than ' +
-                                'your cursor — and is then marked isNew:false even though you have never ' +
-                                'seen it. Nothing is filtered out, so decide what is unseen by MATCHID ' +
-                                'against the ones you have already processed; isNew is a timestamp hint, ' +
-                                'not the answer. Acting on it alone discards exactly the late results this ' +
-                                'unfiltered window exists to preserve. ' +
-                                'This window is the newest `limit` matches and there is no way to page ' +
-                                'past it, so after an absence of more than that many matches the older ' +
-                                'ones are gone — raise historyLimit (max 200) and visit more often. ' +
-                                'Each result comes from the recorded score (resultBasis), which already ' +
-                                'includes extra-time goals but NOT a shootout. Only a D on a row with ' +
-                                'shootoutPossible:true can be hiding one — knockout ties, and friendlies ' +
-                                'played without allowDraw. On shootoutPossible:false (cup GROUP matches, and ' +
-                                'friendlies that asked for draws) a D is a real draw: do not spend a ' +
-                                'get_match on it, and do not discount it as undecided.' +
-                                (usedFallback
-                                    ? ' THESE ROWS ARE THE FALLBACK COPY and carry neither field, so every D ' +
-                                        'here is unresolved: check get_match before drawing any conclusion from ' +
-                                        'one, or call catch_up again once the history endpoint answers.'
-                                    : ''),
+                            // Spread order would let this note win over the cursor note
+                            // above, and it says "nothing is filtered out … decide what is
+                            // unseen by MATCHID" — false of a stream payload, and exactly
+                            // the instruction the cursor exists to retire. An agent
+                            // migrating off sinceIso passes BOTH, so this is the common
+                            // case, not the corner.
+                            ...(unseen !== null
+                                ? {}
+                                : {
+                                    note: 'finishedAt is the scheduled kickoff for cup and league matches, not the ' +
+                                        'completion time, so a late-finished match can carry a timestamp older than ' +
+                                        'your cursor — and is then marked isNew:false even though you have never ' +
+                                        'seen it. Nothing is filtered out, so decide what is unseen by MATCHID ' +
+                                        'against the ones you have already processed; isNew is a timestamp hint, ' +
+                                        'not the answer. Acting on it alone discards exactly the late results this ' +
+                                        'unfiltered window exists to preserve. ' +
+                                        'This window is the newest `limit` matches and there is no way to page ' +
+                                        'past it, so after an absence of more than that many matches the older ' +
+                                        'ones are gone — raise historyLimit (max 200) and visit more often. ' +
+                                        'resultBasis says how each result was reached: "score" (which already ' +
+                                        'includes extra-time goals) or "shootout" (the score was level and ' +
+                                        'penalties decided it — W/L, not D, and penaltyWinner names the side). ' +
+                                        'A D is a real draw except on old rows: matches finished before the ' +
+                                        'shootout was recorded, and any whose events were pruned, come back with ' +
+                                        'resultBasis "score" and shootoutPossible:true. That combination is the ' +
+                                        'only one worth a get_match. On shootoutPossible:false a D is final: do ' +
+                                        'not spend a call on it, and do not discount it as undecided.' +
+                                        (usedFallback
+                                            ? ' THESE ROWS ARE THE FALLBACK COPY and carry neither field, so every D ' +
+                                                'here is unresolved: check get_match before drawing any conclusion from ' +
+                                                'one, or call catch_up again once the history endpoint answers.'
+                                            : ''),
+                                }),
                         }),
                     returned: matches.length,
                     fetched: all.length,
@@ -1778,12 +2014,18 @@ export function buildServer(opts = {}) {
                     // stops an agent from retrying. But a manager with NO SQUAD has
                     // nothing to fetch — reporting that as truncated would have it
                     // retry forever against an empty career.
-                    mayHaveMore: squadUnknown ? true : teamId === null ? false : fetched === null ? true : all.length >= limit,
+                    mayHaveMore: squadUnknown
+                        ? true
+                        : teamId === null
+                            ? false
+                            : servedFromDashboard
+                                ? true
+                                : all.length >= limit,
                     source: squadUnknown
                         ? 'unknown — the dashboard could not read your teams'
                         : teamId === null
                             ? 'no squad yet'
-                            : fetched === null
+                            : servedFromDashboard
                                 ? 'dashboard (capped at 5)'
                                 : 'team history',
                     ...(squadUnknown
@@ -1792,13 +2034,9 @@ export function buildServer(opts = {}) {
                                 'have a squad. Do NOT create another one on the strength of this — call ' +
                                 'catch_up again, or my_squads.',
                         }
-                        : historyError === null || teamId === null
+                        : historyWarning === null
                             ? {}
-                            : {
-                                warning: `Match history could not be read (${historyError}), so this shows only the ` +
-                                    'five rows the dashboard carries. A cup day produces more than that — ' +
-                                    'call catch_up again before concluding anything from it.',
-                            }),
+                            : { warning: historyWarning }),
                 },
             };
             // Opponent squad names and player names are chosen by other players, and