docs(agents): cite installedBy's writers by symbol, and stop implying five

[lilyshen0722]

What

Comment only. No behaviour change.

@sprint-review recounted the installedBy writers (57771). The bot half holds at exactly five. The human half doesn't — the comment listed five sites as though that were the set.

There are at least ten originating human-side writes: podController, authController, personaHireService, podCurationService, agentProfile, registry/install, registry/admin, dmService (twice), and one in this very file — the auto-install inside resolveMentionTarget, which writes senderUserId.

Two changes

Line numbers → symbols. Per the rule #1165 earned: a sha 404s and a grep for a symbol fails loudly, but a line number answers wrongly. Five of the six positions this comment cited had already moved.

The count is now a floor, with the grep that reproduces it. The failure wasn't the number being wrong on the day it was written — it was a number frozen into prose where nothing re-derives it.

Residue, stated in the comment

grep -rn 'installedBy:' backend | grep -v __tests__ also returns queries (agentMemoryView, approvalActionService) and propagations of an existing value. Neither writes an identity. Re-deriving that distinction is what separated the ten from a larger raw count — worth naming, since the next person runs the same grep.

Note for whoever merges

Touches the same comment block as #1216, a few lines apart. Non-overlapping hunks, but land them in either order and re-read the block once.

agentMentionService suite green, tsc clean.

🤖 Generated with Claude Code

[lilyshen0722]

sprint-review gate — one factual correction, and the CI remedy as written will make things worse. Head ae80d983, 2 files (+23/-7), comment-only in both. behind = 82, mergeable_state: unstable.

I ran the reader the comment names rather than trusting the enumeration, since the whole point of this change is that a frozen enumeration goes stale.

The limit: 10 claim is exactly right. grep -n "limit: 10\|limit: 1\b" cli/src/commands/agent.js returns two hits: the message snapshot at :813 and the events fetch at :1214, which is limit: 1 with the matching rationale attached. The comment is the only thing standing between those two lines and a future reader who "harmonises" them.

One member of the bot-side writer list is a query, not a write. podWriteAccessService has exactly one installedBy occurrence in the whole file:

backend/services/podWriteAccessService.ts:46
  const installation = await AgentInstallation.findOne({
    podId,
    installedBy: req.agentUser._id,
    status: 'active',
  }).lean();

That is a filter. The controls hold either way — agentAutoJoinService:80 and the three agentsRuntime sites are genuine writes into a document literal (version, config, scopes, installedBy), so the bot-side category is real; podWriteAccessService just is not a member of it. Everything else I checked lands where the comment puts it: podCurationService writes userId (human), users.ts and agentMemoryView.ts are both find/findOne filters and are correctly filed under queries.

This is the same error the comment scolds an earlier draft for, mirrored — that one filed approvalActionService under queries when it does both; this one files a query under writers. That is not irony so much as evidence for the change's own thesis: the write/query distinction does not survive being carried in prose, in either direction. It does not disturb the conclusion — installedBy is dual-identity and unsafe to key thread state on — so this is a correction, not an objection.

Small tension worth a second look: the comment says "No line numbers and no total, deliberately," and then says the enumeration "reaches twelve." The "floor, not a census" hedge mostly covers it, but the sentence forswears the thing the next sentence supplies, and a number in prose is what froze the last one.

Separately, and worth checking outside this PR: that podWriteAccessService query filters on installedBy: req.agentUser._id. If installedBy really can hold the human installer, that lookup would miss a human-installed agent's own installation. I have not traced the callers or the guards between them, so I am raising it as a question rather than filing it — but it is the same field, one file over, and this PR is the reason to look.

---

The failing check's remedy is right in general and wrong here.

Source changed ⇒ version bumped fails with: "cli/src changed (1 file(s)) but version is still 0.1.18 … bump it, or move the change out of cli/src." The gate is correct to fire even on a comment-only diff — the published tarball ships src/, so the artifact bytes genuinely differ, and its stated rationale ("a published version that maps to two different artifacts") holds for a comment exactly as it does for code. Do not exempt comments.

But do not follow the message literally either. This branch's cli/package.json reads 0.1.18 because it is 82 commits behind; main is at 0.1.26, and 0.1.26 is published. Bumping to 0.1.19 would move the version backwards relative to main and collide on merge. The gate compares base→head within the branch, so it cannot see that its own suggested target is already spent.

Rebase first — that brings cli/package.json to 0.1.26 on its own — then bump to 0.1.27. Same shape as the blocker on #1218, where a bump to 0.3.5 collided with a 0.3.5 already published from main.

behind = 82 against MAX_BEHIND: 40 is a blocker on its own; the Stale-base merge guard shows green here only because it last ran on 2026-08-25 and fires on [opened, synchronize, reopened, edited].