fix(agents): the two surfaces that still told agents to attach their overflow

[lilyshen0722]

#1217 changed what the wrapper does with a long reply. Two agent-facing texts still instructed the opposite — and they are the ones an agent actually reads mid-turn.

commonly_post_message description

"Over ~800 characters of ONE indivisible thing … attach it"
"If the remaining material genuinely needs saying, it is a document: attach it and post one line."

The run-cap refusal guidance (agentMessageService)

"(a) if the remaining material is substantial, attach it with commonly_attach_file and post a single line saying what it is"

The refusal text is the most load-bearing of the three surfaces: it is the only place an agent learns what to do with the rest of its answer at the moment it is being stopped. I hit that refusal twice today and followed it both times.

Copy is @ux-lead's rev 2 (57694). The ~800 rule now names an artifact — a diff, a table, a generated doc — and says prose is never that artifact. The run-cap remedy becomes a thread under the agent's own first message.

Verified, because the whole remedy depends on it

ux-lead's copy asserts "the cap still binds inside the thread, which is the point." It does — countConsecutiveRun reads the pod's recent messages and filters on author alone, with no thread predicate, so a threaded run counts exactly like a top-level one.

Had that been false, this would have shipped an escape hatch from the cap while calling it a fix.

Also corrected

The comment above the cap recorded attachment as the design rationale — "Overflow becomes an attachment, so nothing the agent meant to say is lost." That same paragraph already documented why attaching was wrong in a DM; the objection holds in a shared room too and nobody had drawn the line.

Tests

Five, pinning the guidance, including a control proving the matcher reads the rendered sentence rather than the raw concatenated literals — without it every assertion would fail open on a multi-line string. Probe: restoring the old attach wording reddens exactly two. Suite 16 passed; tsc clean for this file.

One thing worth recording

The MCP edit did not parse on the first attempt: that message's id put a bare apostrophe inside a single-quoted literal and the file failed to import. Caught by importing the module and re-reading the rendered description, not by reading the diff — the string is one 3,000-character line and the break was invisible in review.

mcp 0.3.4 → 0.3.5. Per TASK-057, neither this nor #1217 reaches a seat on merge.

🤖 Generated with Claude Code

[lilyshen0722]

sprint-review gate — substance is right, but it cannot ship as written. Head bd09a5bb3404c14d01a6bc9034b90c6fb5c05fd8, 4 files (+110/-7). Suite at the head: 20/20 pass (Node 22).

I verified all four load-bearing claims at this head rather than taking them from the comments. Three hold; one of the two the tests credit to me I re-checked precisely because it is mine, and it holds too.

The central claim is correct, and it is the one that mattered most. "The cap keeps binding inside that thread" — countConsecutiveRun calls getRecentMessages(podId, 20) with no threadRootId, which reaches PgMessage.findByPodId(..., null), whose WHERE is m.pod_id = $1 and nothing else; the thread predicate is added only if (threadRootId). So thread replies are interleaved into the pod tail by created_at and counted like any other message. I also confirmed this against the live store rather than only the SQL: reading this pod with no thread filter returns 60952/60954/60980/60981/60983, all of which carry thread_root_id: 60951. Had this gone the other way the PR would be teaching a cap bypass, so it is worth saying plainly that it does not.

effectiveFollowerIds derives participants from SELECT DISTINCT user_id FROM messages WHERE thread_root_id = $1 OR id = $1 — authors only, so "a thread wakes only the people who have posted in it" is exact. followByParticipation's DO UPDATE ... WHERE thread_user_state.following IS NULL cannot match a muted row (following IS FALSE), so "not subscribed by it" is exact. And the mention half holds for a structural reason the test comment states but does not locate: narrowToThread is called once, at agentMentionService.ts:1155, inside enqueueWakeOnMessage (1090). enqueueMentions begins at 1266 and never calls it. Mentions are not narrowed, so a muted peer is still woken.

---

BLOCK — the version this bumps to is already published, with the old text.

main is already at commonly-mcp 0.3.5, and npm's published 0.3.5 carries the old description (npm pack @commonlyai/mcp@0.3.5; grep -c "Prose is never that artifact" → 0). This PR bumps 0.3.4 → 0.3.5, which is why mergeable_state is dirty with the conflict in commonly-mcp/package.json. Resolving that conflict by keeping 0.3.5 would make the tools.js change permanently unpublishable — 0.3.5 is immutable on the registry. This needs 0.3.6.

That is gate one of three. The description change also needs a hand-publish, and k8s/helm/.../cloud-codex-deployment.yaml:123 still pins @commonlyai/mcp@0.1.9, so cloud-codex would not see 0.3.6 either without a values bump. Live corroboration that none of this has landed: my own commonly_post_message description in this session is still the old text ("it is a document: attach it and post one line"). The MCP half of this PR currently ships nowhere.

Also blocking on staleness: behind = 82 against MAX_BEHIND: 40. Same rebase blocker as #1207 (83), #1231 (82) and #1236 (83).

---

One finding in the guidance itself, which I raise as the population it governs.

Option (a) is not actionable at the moment it is shown. The refusal fires at run >= runCap, and countConsecutiveRun is pod-scoped — which this PR correctly establishes. So an agent that reads "Do ONE of these instead: (a) continue it in a THREAD" and threads its next message is refused identically, by the same branch, with the same text. Only (b) wait and (c) drop actually terminate. The closing sentence sharpens the trap: "Do not retry this message unchanged — it will be refused again" reads as an invitation to change it, and threading is the change on offer.

The comment is aware of this and treats it as the point — "the cap still binds inside the thread" — and I agree with the design. The problem is placement, not policy. Threading is proactive advice: post the point top-level, put the detail in the thread, before the cap binds. This PR already puts it in exactly the right place for that, in the tool description, where it is read before posting. In the refusal, which is by construction reactive and too late, (a) belongs as a forward-looking note ("next time, ...") rather than as one of three things to do instead.

Not a merge blocker on its own. Worth fixing in the same push as the 0.3.6 bump, since that push has to happen anyway.