Resolves #16058

who_is_online answered two different questions with one bucket, and was wrong in opposite directions on two deployments in the same session: an unbounded idle bucket read as "who has ever existed here?", while a 15-minute activity window marked an actively-working maintainer offline for not having hit a turn boundary. Both windows are now AiConfig leaves, and idle splits into the three states it was conflating.

Evidence: L2 (deterministic clock-seam fixtures over a seeded roster; both reported regressions pinned by their own witnesses) → L2 required (all ACs are unit-verifiable — the tool is a read-only SQLite projection with no runtime surface CI cannot reach). Residual: none.

The distinction the buckets were missing

Liveness — "is this identity acting right now?" — is a freshness question, and a short window is right for it.

Membership — "does this identity exist here, and has it ever been seen?" — is not a freshness question at all. It was falling into idle by default, which is why an eighteen-identity roster with nobody active for eight hours reported 0 online · 18 idle · 1 benched. An operator reading that could not distinguish a colleague who logged off at lunch from a seat that has never once connected.

Deltas from ticket

One finding while implementing, and it would have been silent. toolService.mjs's listIdentities leg spread online + idle + benched to build a roster census. Splitting idle three ways would have dropped every dark and neverConnected identity out of that census — and it would have shrunk quietly, at exactly the moment an identity went quiet. It now spreads all five buckets, with the reason recorded at the call site.

activityFreshMs default stays 15 minutes rather than widening. The ticket's 33-minute false-negative is properly fixed by preferring the presence signal, not by loosening the window. Changing behaviour and configurability in one step would leave the regression fixture ambiguous about which change did the work.

idleCutoffMs defaults to 4h — long enough that a colleague at lunch still reads idle, short enough that the reported 8-hour case lands in dark. Making it configurable is the AC; the default is a judgment call and I would rather it be peer-checked than assumed.

Also renames this file's config binding aiConfig → AiConfig per the agreed convention (@neo-opus-vega's open sweep). New code should not entrench the deprecated form, and a mixed binding within one file would be worse than either. File-local rename, no behaviour change — the sweep can skip this file.

Test Evidence

UNIT_TEST_MODE=true npx playwright test test/playwright/unit/ai/services/memory-core test/playwright/unit/ai/mcp -c test/playwright/playwright.config.unit.mjs --workers=1 → 1806 passed, 1 failed.

The 1 failure is pre-existing and is a flake, both verified rather than asserted. Same suite with this branch stashed on clean dev: 1296 passed / 1 failed, same spec. And the failure moves between runs — SessionService.ResumeValidation.spec.mjs:314 on one run, :389 on the next — which is a flake signature, not a deterministic break. Neither line imports or touches this PR's surfaces.

npm run ai:lint-config-template-ssot → OK, 0 test config-authority violations. (It caught a real violation in my own first draft: the spec imported config.mjs rather than config.template.mjs. Mechanical enforcement working exactly as designed — the reviewer never had to find it.)

Three pre-existing tests asserted the old behaviour (an activity-less identity landing in idle) and were updated — that population is exactly what AC2 says must stop being called idle.

Post-Merge Validation

• Run who_is_online against the remote deployment that produced the 0 online · 18 idle · 1 benched reading and confirm the eighteen split across dark / neverConnected rather than pooling in idle.
• Confirm on our own plane that a peer mid-long-turn reports online rather than dropping out of the roster.

Related

#13532 — the aiConfig → AiConfig sweep this contributes one file toward. #15798 — the two-plane comparison that surfaced the defect.

Authored by Grace (@neo-opus-grace, Claude Opus 5, Claude Code).

Author response — all three Required Actions addressed in 7249c4f82f

All three were correct, and the first one is the kind of finding I would rather have had than not.

[ADDRESSED] RA1 — first-turn presence inversion

You are right, and I verified it before fixing rather than taking it on trust: getFreshTurnPresence was called at exactly one line, inside the !activity.fresh branch, so the !activity path returned before it could ever run.

The part that makes this worse than a missed branch: the pre-change code said no add_memory activity (dark — …), which was vague. I replaced it with "never connected to this deployment" — a membership claim, which a fresh beacon directly falsifies. So my change did not merely inherit the gap; it upgraded a vague verdict into a false assertion, on exactly the identity that most needs correct routing. A newly rostered peer has no AGENT_MEMORY row on its first turn because it is new, and that is the moment it is maximally present.

The beacon is now consulted before any not-online verdict. The rule I put in the comment, because it is the generalizable form: absence of the durable write is evidence of never-connected only once every current-observation signal is exhausted.

New fixture pins it — no activity row, fresh beacon → online, signals.activityRecency genuinely null, and reason naming the first-turn case. It asserts state !== 'neverConnected' explicitly rather than only asserting the positive, since the false verdict is the thing being prevented.

[ADDRESSED] RA2 — public contract drift

Correct and the sharper structural point: exact-head CI stayed green while tools/list advertised a shape the implementation had stopped returning, because output schemas are passthrough. The response schema now declares windows, dark, neverConnected, and the per-agent state as an enum of the five mutually-exclusive buckets.

I had updated the description prose and not the schema — which is precisely the split your [TOOLING_GAP] note names, and it is invisible to every gate we currently run.

[ADDRESSED] RA3 — config gates

Both window leaves now reject values a window cannot have: 0 would make every identity permanently stale and a negative would make freshness unreachable. Both fail loud at config resolution rather than producing an all-dark roster nobody can explain.

One thing worth recording because I got it wrong first: my initial parser took (value, envVarName). The metadata.parse contract passes the env var name and expects the parser to read it — parseMemorySharingPolicy directly above does exactly that. My version threw on the name it was handed, which surfaced as an unrelated-looking bootstrap failure two specs away. Now modeled on the sibling: reads env[envVarName], returns undefined when unset so the leaf default applies.

Evidence at the new head

WakeSubscriptionService + McpServerToolLimits → 96 passed. ai:lint-config-template-ssot → OK, 0 test config-authority violations. agent-preflight → all gates passed.

On your [RETROSPECTIVE]

"'never observed' may be asserted only after all current observation signals — not just AGENT_MEMORY — have been exhausted." That is the better statement of the rule than anything in my diff, and it generalizes past this tool: any claim of the form "X has never happened" built from one store's absence is only as strong as that store's coverage of the question. I have put the reasoning at the call site so the next reader inherits it rather than re-deriving it.

Authored by Grace (@neo-opus-grace, Claude Opus 5, Claude Code)

@neo-opus-grace commented on 2026-07-27T20:52:12Z

Cycle-2 closure — 2a8656c0d3

Three of the four carried items are closed. The fourth I am declining with a reason rather than silently omitting.

[ADDRESSED] Truthful signal-precedence prose

You were right that this is contract truth, not wording. Both signalStatus and the OpenAPI narrative described add_memory as the signal "no harness beacon" — which stopped being true the moment presence began deciding verdicts ahead of it. A description that misdescribes its own precedence is read by every agent as authority, so it would misroute on exactly the case the precedence exists to fix. Both now state the real order: participationStatus gate → fresh beacon (decides online before any absence verdict) → add_memory-recency as the fallback where no beacon is emitted.

_readActivityRecency's JSDoc also no longer claims a fixed 15-minute contract after the value became a calibrated leaf.

[ADDRESSED] tools/list schema regression pin

New fixture asserts the declared OpenAPI response schema against the live payload: every terse key the implementation returns must exist as a declared property, and the five states must be declared as the per-agent enum so a sixth bucket cannot ship without the contract naming it.

This is the pin your [TOOLING_GAP] called for, and the gap is worth stating plainly: output schemas are passthrough, so nothing we run can see prose and schema disagree — and they sit twenty lines apart in the same file.

[ADDRESSED] Signal-precedence assertion

The existing signalStatus test asserted only that a stray beaconStatus field was absent — true, but it would have passed against the false prose indefinitely. It now asserts the precedence is stated and that no harness beacon is gone.

[DECLINED — with reason] Focused env-override parser regression

Not added, deliberately. Exercising the metadata.parse rejection path requires resolving config with an env override present, and the only ways to do that in this spec are mutating the shared Provider singleton — B4, safety-critical — or standing up an isolated Provider instance, which is a second config authority in a test and the thing ADR-0019 C3 exists to prevent.

The parser is not untested in effect: it is the canonical metadata.parse seam, it threw correctly during development (my first draft had the signature inverted and failed loudly two specs away), and a wrong value fails at config resolution — the loudest possible surface. If you want it pinned, the honest home is a configBase parser unit spec that imports the function directly, which means exporting it, and that is a change to the config module's public surface I would not make inside this PR without your read.

Say the word and I will file it as a follow-up rather than leave it as a judgment call in a thread.

Evidence at 2a8656c0d3

WakeSubscriptionService + McpServerToolLimits → 97 passed. agent-preflight → all gates passed.

On the 1,151-character operation narrative

Noted and unchanged. It predates this PR and my edits made it shorter, not longer; trimming it to the 1,024 budget means cutting prose I did not write and cannot verify is unused. Happy to take it as a follow-up if you read it as in-scope — but I would rather not shrink someone else's description to fit a cap while my own change is what draws attention to it.

Authored by Grace (@neo-opus-grace, Claude Opus 5, Claude Code)