@rubytech/create-realagent-code 0.1.572 → 0.1.574

package/payload/platform/plugins/admin/skills/admin-user-management/SKILL.md

@@ -13,7 +13,8 @@ This skill manages who has admin access to this account. It wraps six MCP tools
 
 | Tool | Purpose |
 |---|---|
-| `admin-add` | Add a new admin. Requires a name. PIN is optional: omit it and a unique 4-digit PIN is generated. PIN must be at least 4 digits and unique across all users on the device. |
+| `admin-add` | Add a new admin. Requires a name. PIN is optional: omit it and a unique 4-digit PIN is generated. PIN must be at least 4 digits and unique across all users on the device. `phone` and `telegram` are optional channel bindings — pass them and the new admin is born reachable on those channels. |
+| `admin-bind` | Set the `phone` and/or `telegram` chat id on an admin. Defaults to the calling admin; pass `userId` to bind someone else and that also needs `confirm: true`, because a binding decides whose identity an inbound resolves to. Sets only what you pass; an omitted field is left alone. |
 | `admin-remove` | Remove an admin by `userId` (find IDs via `admin-list`). The last admin on the account cannot be removed. The user's device-level entry is retained so they can still administer other accounts. |
 | `admin-list` | List all admins on this account with names and roles. |
 | `admin-update-pin` | Update an admin's PIN. Defaults to the calling admin if no `userId` is given. PIN must be at least 4 digits and unique across all users on the device. |
@@ -24,6 +25,35 @@ This skill manages who has admin access to this account. It wraps six MCP tools
 
 The remote-access password is the *outer* gate — the password the Cloudflare tunnel asks for before the PIN screen — and it is independent of the PIN. Each admin has their own; setting or revoking one never touches another admin's password or anyone's PIN. The PIN still does identity (it names the admin in session rows); the access password just decides who can reach a tunnel-exposed install at all. On an install upgraded from the old single shared password, the owner's existing password migrates onto their own record automatically on first boot, so nobody is locked out.
 
+## Channel bindings decide whether an answer reaches a second channel
+
+An admin's `users.json` entry carries two optional bindings, and they are what
+lets one answer reach every channel that person holds rather than only the one
+the message arrived on.
+
+`phone` is the E.164 number. It identifies a WhatsApp sender as this person, and
+it is also the address used to reach them on WhatsApp when a turn arrives
+somewhere else. `telegram` is the chat id, matched exactly, doing the same two
+jobs for Telegram. They are not interchangeable, and two-way reach needs both.
+
+`account.json` `whatsapp.adminPhones` is a different thing: an allowlist saying
+a number may reach the admin agent. It grants access; it does not say whose
+number it is, which is why adding a phone there never binds anyone.
+
+When a binding is missing, the failure is silent to the person messaging. These
+lines in `server.log` name it:
+
+| Line | Means |
+|---|---|
+| `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | this sender resolves to no admin, so no second door is looked for |
+| `[channel-fanout] op=no-target origin=… reason=no-admin-user` | the same fact, at the fan-out |
+| `[channel-fanout] op=fan-out reached=… notReached=…` | which doors actually received the answer |
+
+A Telegram bot owned by a `role:'client'` sub-account can never resolve an
+admin: both resolvers return null on a client account before reading any chat
+id. Setting `telegram` will not help there; the bot has to live on the house
+account.
+
 ## The three-store invariant
 
 Admin identity lives in three places that must stay in lockstep:
@@ -32,7 +62,7 @@ Admin identity lives in three places that must stay in lockstep:
 2. `users.json`: device-level PIN authentication. This is the source of truth at login.
 3. The Neo4j graph: `:AdminUser` + `:Person` + `OWNS` + `ADMIN_OF` edges. Display and graph identity.
 
-`admin-add` writes all three. `admin-update-pin` writes `users.json` only (the other stores carry no PIN). If any leg fails, the tool returns `is_error: true` and `server.log` carries a `[admin-auth-store] action=… userId=… result=fail store=…` line naming which leg failed and what was already written. When you see that line, tell the owner the record is half-written and may need manual reconciliation.
+`admin-add` writes all three. `admin-update-pin` and `admin-bind` write `users.json` only (the other stores carry neither the PIN nor the channel bindings). If any leg fails, the tool returns `is_error: true` and `server.log` carries a `[admin-auth-store] action=… userId=… result=fail store=…` line naming which leg failed and what was already written. When you see that line, tell the owner the record is half-written and may need manual reconciliation.
 
 ## Never write `account.json` directly
 

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Real Agent ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:d924bab338240bf9b1ffa6dd391f2428bf182d40da44677bd3bde3ab53b7a0ba
+content-hash: sha256:327b61590f8a5e2dd2a654cd848edd19eccf7df3acecccad012160e8923e8fa0
 brand: realagent-code
 product-name: Real Agent
 ---
@@ -1946,74 +1946,67 @@ defect. Turns that answered no inbound — subagent side-chains, turns driven fr
 claude.ai — are deliberately outside that set: the credit guards are what keep
 them out of a customer's chat.
 
-Each door's `src/parity.test.ts` asserts the contract end to end against a real
-JSONL and the real follower.
-
-**Six discard sites, each now logged.** A follower outcome is dropped at:
-
-| File | Guard | `reason=` |
-|---|---|---|
-| `telegram-channel/src/server.ts:241` | `pendingTurns <= 0` | `no-credit` |
-| `webchat-channel/src/server.ts:378` | `pendingTurns <= 0` | `no-credit` |
-| `whatsapp-channel/src/server.ts:481` | `pendingTurns <= 0` | `no-credit` |
-| `whatsapp-channel/src/server.ts:489` | `consumedInbounds <= 0` | `no-consumed-inbound` |
-| `whatsapp-channel/src/server.ts:617` | `pendingTurns <= 0` (2nd follower) | `no-credit` |
-| `whatsapp-channel/src/server.ts:620` | `consumedInbounds <= 0` (2nd follower) | `no-consumed-inbound` |
+**Discard sites.** The WhatsApp and Telegram followers and their credit ledgers
+were removed, so those two doors now have none: one emitter reads the JSONL and
+the fan-out decides where an answer goes. Only webchat still carries credit
+guards, in `webchat-channel/src/server.ts`, and `src/parity.test.ts` survives
+for that door alone.
 
 ```
-[<door>-channel]     op=turn-drop sessionId=… messageId=… finalBytes=… reason=…
-[<door>-turn-census] op=census sessionId=… pending=… held=<0|1> heldMessageId=… heldAgeMs=… lastMessageId=…
+[channel-fanout] op=fan-out reached=… notReached=… segments=… messageId=… sessionId=…
+[channel-parity] op=parity-census sessionId=… rendered=… sent=… missing=… missingIds=…
 ```
 
-Any `op=turn-drop` with `finalBytes>0` is a lost answer. The census runs every
-60 s per follower; `held=1` with `heldAgeMs` rising across ticks is a hold that
-never resolved, and `pending` not returning to 0 with no inbound in flight is
-credit drift.
+`missing` above zero is a lost answer, and `missingIds` names each one. The
+census prints every cycle, including when the counts agree: an absent line means
+the census stopped, never that delivery is healthy.
 
-**Read them in the right file.** Both lines are emitted by the *channel MCP
-server*, whose stderr is teed to `${LOG_DIR}/mcp-<serverName>-<sessionId>.log`
-(`claude-session-manager/src/channel-spawn-tee.ts`). They are **never** in
-`server.log`, which carries the gateway-side half only — `op=turn-end`,
-`op=turn-answer-absent`, `delivered=`. Grepping `server.log` for a drop returns
-nothing and means nothing.
+## What a second door actually requires
 
-```bash
-# the discard and the hold, per session
-grep -E 'op=(turn-drop|census)' ~/.<brand>/logs/mcp-telegram-channel-*.log | tail -20
-# the gateway's view of the same turn
-grep -E 'op=(turn-end|turn-answer-absent)' ~/.<brand>/logs/server.log | grep <sessionId>
-```
+Reaching a door other than the one the message arrived on needs two facts.
 
-**A seventh discard site, and the one nothing was reading.** An answer that
-survived every guard above could still be produced and thrown away at the last
-step, because the gateway resolved its destination from admin identity rather
-than from the channel it came in on. A public visitor has no admin identity, so
-the resolver returned no target: nothing was attempted, no transport failed, and
-the line read `reached=none notReached=none`.
+**The person must be resolvable from the turn's sender.** That resolution reads
+one place: the admin's `users.json` entry. `phone` (E.164) identifies a WhatsApp
+sender; `telegram` (the chat id, matched exactly) identifies a Telegram sender.
+`account.json` `whatsapp.adminPhones` is a different store with a different job:
+it says a number may reach the admin agent, not whose number it is, which is why
+adding a phone there binds nobody. Set the bindings with `admin-bind`, or at
+creation with `admin-add`'s `phone` and `telegram`.
 
-The turn-end body now carries the channel server's own spawn `role`, and that is
-the only thing that decides the destination:
+**The other door must hold a live target for that person.** `phone` addresses
+WhatsApp when a Telegram turn wants to reach it, and `telegram` addresses
+Telegram from a WhatsApp turn. Two-way reach needs both fields, not one.
 
-| `role=` | Where the answer goes | `op=fan-out` |
-|---|---|---|
-| `public` | every segment through the posting key's own transport; no identity resolver, no registry read | never emitted |
-| `admin` | every live door the person is reachable on, via `fanTargetsFor` | emitted |
-| absent or unrecognised | nowhere. 400, plus one `op=turn-role-absent … evicted=<yes\|no>` | never emitted |
-
-`op=turn-end` and `op=turn-strand-anomaly` both name the role, so no outcome is
-unattributable.
-
-A roleless POST has one cause: a channel server from a build predating the field,
-still attached to a session that outlived the platform restart. It reconnects its
-stream, so nothing respawns it, and left alone it would post roleless turn-ends for
-the life of that session. `evicted=yes` says the gateway dropped its subscriber, so
-the next inbound spawns a server on the current build: one turn is lost per session
-rather than all of them. That turn's answer is deliberately not delivered to the
-posting key, because doing so would restore the very fallback whose reachability hid
-the original defect. The standing check is one line per door per minute, over a
-rolling hour:
+The three lines that name each failure:
+
+| Line | Means |
+|---|---|
+| `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | no binding, so no second door is even looked for |
+| `[channel-fanout] op=no-target origin=… reason=no-admin-user` | the same fact, observed at the fan-out |
+| `[channel-fanout] op=no-target origin=… reason=origin-not-live` | the door holds no live target for this key |
+
+A Telegram bot owned by a `role:'client'` sub-account can never resolve an
+admin: both resolvers return null on a client account before reading any chat
+id. No binding fixes that; the bot has to live on the house account.
+
+`[whatsapp-account-scope] op=non-uuid-account caller=fan-out` means the fan-out
+was handed a Baileys credential dirname where a platform UUID belongs. That is
+the defect that stranded a live admin answer, and the line exists so the next
+occurrence announces itself instead of being inferred from a silent miss.
+
+**Read them in `server.log`.** Both are emitted by the ui-server, which now owns
+the one emitter between the session JSONL and every channel. The per-door
+`op=turn-drop` and `op=census` lines that used to sit in
+`${LOG_DIR}/mcp-<serverName>-<sessionId>.log` are gone with the per-channel
+followers that were removed, and so is `delivered=fallback`, which no code
+emits.
 
 ```bash
+# every answer and where it went
+grep -E 'op=(fan-out|parity-census)' ~/.<brand>/logs/server.log | tail -20
+# one session
+grep 'op=fan-out' ~/.<brand>/logs/server.log | grep <sessionId>
+```
 # the standing read; any undeliveredPublic>0 is a failure
 grep -E 'op=census' ~/.<brand>/logs/server.log | grep delivery-census | tail -5
 # a visitor's answer that reached nobody, or a turn-end that named no role
@@ -2817,6 +2810,29 @@ Two things to know:
 Text only for now. Photos, files and voice notes are not available on Telegram
 from the dashboard.
 
+## Building your own Telegram functionality
+
+Telegram is a core plugin, so it is on every install and cannot be switched off.
+
+Beyond sending and reading messages, Real Agent can reach every one of the
+185 things Telegram's Bot API can do: buttons under a message, changing a
+message after you sent it, uploading a photo or a document, pinning, polls, chat
+administration, and opening a small web page inside the Telegram chat itself.
+
+Just ask for what you want. "Send the team a message with Yes and No buttons",
+"update that job card to say he's on site", "pin the rota to the group".
+Real Agent loads its Telegram build skill, which lists every available
+method and how to call it.
+
+Five of the 185 are deliberately refused, because they would break your own
+inbound messages: setting or deleting the webhook by hand, polling Telegram for
+updates instead, and the two that move the bot off Telegram's cloud servers.
+Setting up or repointing a webhook is what the Telegram setup skill is for.
+
+If Telegram publishes a new capability it works here immediately, with nothing
+released first. A scheduled check reconciles what Real Agent knows about
+against Telegram's live documentation and reports anything that changed.
+
 ---
 # Outlook
 Source: https://docs.getmaxy.com/outlook-guide.md
@@ -2886,9 +2902,19 @@ Mail only: calendar and contacts tools refuse on a shared mailbox and say so. If
 
 When the admin agent drafts or sends a message to a known contact, it reads that contact's record first and applies any routing the record carries, for example a preferred send-to address, showing the result for your approval before anything is sent.
 
+## What an empty Drafts folder does not prove
+
+If a draft is gone from Drafts and a copy of it is in Sent Items, that does **not** mean this platform sent it. An external mail client signed in to the same mailbox produces exactly the same folder state, and so does a person clicking send on their phone. Never report that Real Agent sent something on the strength of folder state alone.
+
+Two other things look alarming and are the same blind spot. A message that has left the Drafts folder still fetches by id, and while it remains a draft object it still comes back with no `from` — so "it still fetches" is not "it is still a draft". Read `isDraft` and `parentFolderId`, which every mail read now returns.
+
+The one statement to trust is the hourly reconcile's verdict, `op=draft-reconcile … outcome=`. It compares a ledger of every draft this platform created and sent against what the mailbox actually holds. `outcome=sent-not-by-maxy` means the platform made the draft, never sent it, and it left the folder anyway.
+
+Naming *what* sent it needs the mailbox tenant's Microsoft 365 unified audit log, where a `Send` record carries the client string. This plugin's delegated permissions cannot read it — the mailbox owner's M365 administrator pulls it. Say that, rather than guessing.
+
 ## Observability
 
-All log lines start with `[outlook-mcp]` and write to `server.log`. They are key=value, account-scoped:
+All log lines start with `[outlook-mcp]` and write to `server.log`, except the draft reconcile, which the scheduling heartbeat spawns and whose lines land in `check-due-events.log`. They are key=value, account-scoped:
 
 | Event | Line shape |
 |-------|------------|
@@ -2940,6 +2966,13 @@ All log lines start with `[outlook-mcp]` and write to `server.log`. They are key
 | Draft-send request | `draft-send-request account=<id> id=<draftId>` |
 | Draft sent | `draft-sent account=<id> id=<draftId> status=202` |
 | Draft-send failed | `draft-send-failed account=<id> id=<draftId> error=<msg>` |
+| Ledger row written | `draft-ledger op=<created\|sent> account=<id> mailbox=<addr> draftId=<id> tool=<t> route=<r\|null>` — one per draft created and per draft sent, the left-hand side the reconcile compares the mailbox against |
+| Ledger row lost | `draft-ledger-failed op=<created\|sent> account=<id> draftId=<id> error=<msg>` — the row was not written; the mail still went. A `sent` row lost here can make a real Real Agent send read as `sent-not-by-maxy` later |
+| Draft reconciled | `draft-reconcile account=<id> mailbox=<addr> draftId=<id> outcome=<still-draft\|sent-by-maxy\|sent-not-by-maxy\|deleted\|unreadable> createdTs=<iso> sentDateTime=<iso\|null> parentFolderId=<id\|null> ageMs=<N>` — plus `sentCopyId=`/`sentCopyTo=`/`sentCopyAt=` on `sent-not-by-maxy`, and `status=`/`code=` on `unreadable`. **In `check-due-events.log`, not `server.log`** |
+| Reconcile census | `draft-reconcile-census account=<id> total=<N> stillDraft=<N> sentByMaxy=<N> sentNotByMaxy=<N> deleted=<N> unreadable=<N>` — **every pass including an all-zero one, so an absent census means the reconcile stopped running** |
+| Reconcile pruned | `draft-reconcile-pruned accounts=<N> removed=<N> kept=<N>` |
+| Reconcile skipped | `draft-reconcile-skipped reason=no-vendor-app` — this brand ships no Outlook app; distinct from "did not run" |
+| Reconcile could not run | `draft-reconcile-failed error=<msg>` — exit 1 |
 
 ## Diagnostic paths
 
@@ -2956,6 +2989,19 @@ grep -E "^\[outlook-mcp\] (mail-reply|draft-created)" ~/.maxy/logs/server.log \
   | grep -E "threaded=true|op=reply" | grep -E "convId=(null)?( |$)" | head
 ```
 
+```bash
+# One draft's whole lifeline: created, then a verdict per hourly pass.
+grep -E "op=draft-ledger|op=draft-reconcile" ~/.maxy/logs/check-due-events.log | grep "draftId=<id>"
+
+# Did the reconcile stop? An absent census IS the failure signal.
+grep -c "op=draft-reconcile-census" ~/.maxy/logs/check-due-events.log
+
+# Confirm a sent-not-by-maxy: this must be EMPTY for the window in question.
+grep -E "op=request tool=outlook-(draft-send|mail-send|mail-reply)" ~/.maxy/logs/mcp-outlook-*.log
+```
+
+Attribution triage: `outcome=sent-not-by-maxy` with the send grep above empty means this platform made the draft, never sent it, and it left the folder anyway — an external mail client on the same mailbox. If the send grep is **not** empty for that draft id, suspect a lost ledger row instead and check for `draft-ledger-failed`.
+
 Threading triage: **absence of a `convId` on a threaded write means threading was lost.** `draft-created threaded=false convId=null` is correct and expected — a new message has no parent conversation. `draft-created threaded=true convId=null` is a fault: Graph returned a reply draft that names no conversation, and the reply will land detached from the original.
 
 Latency triage: `mail-list count=0 elapsedMs<200` consistent → permissions issue; `elapsedMs > 5000` → Graph slowness or DNS.
@@ -4144,24 +4190,43 @@ both `kind: 'specialist'` and differ only by origin.
   repair, and it is not what runs unattended: an agent runs only when something
   dispatches it, an inbound message is operator-initiated, so the only autonomous
   path is the scheduler. The modal says so and points at the routines instead.
-  **A file in the LIVE directory whose name also exists under
-  `<accountDir>/plugins/*/agents/` is excluded from this set.** `agent-builder`
-  copies the authored file into `specialists/agents/` because presence there is
-  what makes an agent dispatchable, so the live directory says nothing about who
-  wrote the agent and every activated user-created specialist used to render
-  twice, the second time as Shipped. The account plugin tree is the authorship
-  evidence and its row wins; it is the same discriminator `disable` requires.
-  Both gates read filenames off disk, so a plugin file whose frontmatter does not
-  parse still suppresses its live twin — it is authored either way, and
-  `specialistsSkipped` is what reports the parse failure. **The exclusion covers
-  both account directories, live and quarantine.** It was live-only while only a
-  shipped agent could be quarantined; now that an authored specialist can be
-  switched off, its specialist row carries the plugin, the skills, the detail
-  route and its own disabled state, so a second row from the shipped walk would
-  be a duplicate with none of that. The bundled templates are never deduped: a
-  bundled name is shipped by definition. Each exclusion logs
-  `op=list-shipped-dedup file=<name>` and the count rides `op=list` and the
-  response as `deduped`.
+  **A file in the LIVE or QUARANTINE directory whose name also exists under
+  `<accountDir>/plugins/*/agents/` is excluded from this set only when the two
+  files agree.** `agent-builder` copies the authored file into
+  `specialists/agents/` because presence there is what makes an agent
+  dispatchable, so the live directory says nothing about who wrote the agent and
+  every activated user-created specialist used to render twice, the second time
+  as Shipped. But the filename alone was also not evidence that the live file IS
+  that copy: `computeSpecialistDomains` builds the spawn manifest from the live
+  file, so an excluded row could describe an agent nobody would run, and a
+  premium agent — which reaches an account only through the live directory, since
+  the bundled templates carry no `--` name — lost its only row to an authored
+  file of the same name, its risk class replaced by that file's. **The test is
+  the three fields the card shows and the prompt reads: `name`, `description`,
+  and `tools` compared as a set.** Agreement means one row, exactly as before.
+  Disagreement means both rows render and `op=list-shipped-divergent` names both
+  files and the differing fields. Tools compare as a set rather than as the raw
+  line, because a reordered `tools:` declares the same surface and derives the
+  same class. The body is never compared: the card does not render the system
+  prompt, so a body-only edit does not make the row wrong. A read failure on
+  either side also keeps the row, because an unreadable file cannot be proven
+  equal to anything and keeping it hides nothing — but it is reported as a
+  compare failure, not as a divergence, since nothing was read to disagree. An
+  authored file that does not parse therefore no longer suppresses its live
+  twin. **That test answers a different
+  question to the write gates.** `disable` and `enable` still key on the filename
+  alone, because authorship is a property of the tree a file sits in, not of its
+  frontmatter, so the operator keeps the control on an agent of their own whose
+  frontmatter is broken. **The comparison covers both account directories, live
+  and quarantine.** It was live-only while only a shipped agent could be
+  quarantined; now that an authored specialist can be switched off, its
+  specialist row carries the plugin, the skills, the detail route and its own
+  disabled state, so a second row from the shipped walk would be a duplicate with
+  none of that. The bundled templates are never compared: a bundled name is
+  shipped by definition and has no authored twin to be a copy of. Each exclusion
+  logs `op=list-shipped-dedup file=<name>`; each kept pair logs
+  `op=list-shipped-divergent`. Both counts ride `op=list` and the response, as
+  `deduped` and `divergent`.
 
 The former "Public" flyout toggle in the account menu was removed; this page is
 the sole agent surface.
@@ -4331,7 +4396,7 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
 
 | Route | Behaviour |
 |-------|-----------|
-| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `riskRule`, `riskReason`, `unresolved` and `disabled`. A live-directory candidate whose filename also exists under `plugins/*/agents/` is dropped and counted, so an activated user-created agent is listed once. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped, deduped, riskSurfaceFailed}`. 401 when the session maps to no account. |
+| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `riskRule`, `riskReason`, `unresolved` and `disabled`. A live-directory or quarantine-directory candidate whose filename also exists under `plugins/*/agents/` is dropped and counted only when the two files agree on `name`, `description` and the `tools` set, so an activated user-created agent is listed once and a divergent or colliding pair renders both rows. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped, deduped, divergent, riskSurfaceFailed}`. 401 when the session maps to no account. |
 | `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=` or `?origin=`, returns a public agent's config fields + four owned docs + a `present` map (a missing or unreadable doc is `''`/`present.<role>=false`, never a 500). With `?plugin=`, that plugin's user-created specialist; with `?origin=shipped`, the shipped one. Both specialist shapes add `{risk, riskiestTool, riskRule, riskReason, unresolved, byTool, disabled}`, where `byTool` is one class per declared tool. Selection is explicit rather than inferred, because a premium file and a user-created specialist under a plugin of the same name produce the same slug. Unknown 404s, 401 as above. |
 | `POST /api/admin/agents/:slug/disable?accountId=` | Agents the operator authored only, enforced here rather than left to the UI: a slug NOT present under `plugins/*/agents/` 404s (`reason=not-user-created`), and the message names suspending the routines as what stops a shipped agent instead. An authored slug with no copy in `specialists/agents/` 409s (`reason=not-dispatchable`): it is already not dispatchable, so there is nothing to move and nothing to record. Otherwise it moves the file from `specialists/agents/` to `specialists/agents-disabled/` and returns `{ok, moved:true}` — the only outcome, since the two other cases refuse. It writes NO store entry: `agents-disabled.json` exists to stop provisioning re-delivering a withheld shipped file, and provisioning never writes the account plugin tree. Returns `routingReconciled`, false when either AGENTS.md pass threw; the move already happened and already stopped dispatch, so the request is not failed and the caller is told rather than left assuming the prose is right. Same `accountId` contract as delete. |
 | `POST /api/admin/agents/:slug/enable?accountId=` | Takes NO authorship check, and that asymmetry with disable is deliberate: an install that switched a shipped agent off under the old gate must still reach this route, or inverting the gate strands it. For an authored slug the quarantined file is the whole state — 404 when it is absent, `restored:true` when it moves back, and the store is never touched. For a shipped slug it covers both of the old disable's outcomes: a quarantined file moves back (`restored:true`), and a bundled-only agent has nothing to move so clearing the store entry is the whole job (`restored:false`), which is what stops provisioning withholding it. 404 only when neither the quarantine directory nor the store knows the slug. The store is read strictly first, because this is the read half of a read-modify-write that rewrites the file whole, and it is written back only when an entry was actually removed — so enabling never creates a store an account did not have. |
@@ -4377,11 +4442,13 @@ on** (`accountId=<id8>`) — a well-formed answer about the wrong account is
 otherwise indistinguishable from a correct one, which is exactly how an empty
 Agents page survived undiagnosed on a multi-account install.
 
-- `op=list accountId=<id8> agents=<n> specialists=<m> skipped=<x> specialistsSkipped=<y>`
-  — the heartbeat. Compare `accountId` against the account the operator is
-  viewing; `skipped>0`/`specialistsSkipped>0` is a malformed-source signal the
-  page renders as a banner, and `specialists=0` with user plugins present is the
-  broken-walk signature.
+- `op=list accountId=<id8> agents=<n> specialists=<m> shipped=<s> skipped=<x>
+  specialistsSkipped=<y> shippedSkipped=<z> deduped=<d> divergent=<v>` — the
+  heartbeat. Compare `accountId` against the account the operator is viewing;
+  `skipped>0`/`specialistsSkipped>0`/`shippedSkipped>0` is a malformed-source
+  signal the page renders as a banner, and `specialists=0` with user plugins
+  present is the broken-walk signature. `deduped` and `divergent` are described
+  under their own lines below.
 - `op=detail accountId=<id8> slug=<…> kind=<public|specialist>` — with
   `present=<comma-list|none>` on the public branch, where a role absent for an
   agent expected complete is the missing-doc signature. One
@@ -4408,13 +4475,32 @@ Agents page survived undiagnosed on a multi-account install.
 - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
   `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
   graph-cleanup throw).
-- `op=list-shipped-dedup file=<name>` — one line per live-directory candidate
-  dropped as an authored duplicate, with `deduped=<n>` on the `op=list` line and
-  in the response. `shipped + shippedSkipped + deduped` equals the number of
-  distinct `.md` names across the three source directories, so a listing that
-  does not add up is visible without reproducing anything. The over-exclusion to
-  watch for is a `deduped` line naming a file that is also a bundled or premium
-  agent: the authored file then hides a genuinely shipped one.
+- `op=list-shipped-dedup file=<name>` — one line per live-directory or
+  quarantine-directory candidate dropped as an authored duplicate, with
+  `deduped=<n>` on the `op=list` line and in the response. `shipped +
+  shippedSkipped + deduped` equals the number of distinct `.md` names across the
+  three source directories, so a listing that does not add up is visible without
+  reproducing anything. The over-exclusion to watch for is a `deduped` line
+  naming a file that is also a bundled or premium agent: the authored file then
+  hides a genuinely shipped one, which now requires it to have reproduced that
+  agent's `name`, `description` and `tools` exactly.
+- `op=list-shipped-divergent file=<name> found=<path> authored=<path>
+  fields=<comma-list>` — one line per candidate KEPT because it does not match
+  the authored copy, naming both files and which of `name`, `description`,
+  `tools` differ. Without it a divergence emits nothing: both files parse and the
+  row renders green, so "the row is stale" is indistinguishable from "the agent
+  changed" without diffing the account tree by hand. `found=` rather than
+  `live=`, because the candidate may have come from the quarantine directory and
+  the path itself says which. `divergent=<n>` rides the `op=list` line and the
+  response. A kept candidate is parsed like any other, so it lands in `shipped`,
+  or in `shippedSkipped` when its own frontmatter carries no `name:` — either
+  way `divergent` is never a fourth term and the identity above is unchanged.
+- `op=list-shipped-compare-failed file=<name> side=<found|authored>
+  reason="<msg>"` — a frontmatter read threw during that comparison. The row is
+  kept, because an unreadable file proves nothing, but it is **not** counted in
+  `divergent`: "could not read one of them" and "the two disagree" are different
+  facts, and reporting the first as the second would put drift in the count that
+  nobody observed.
 - `[agents] op=risk account=<id8> slug=<name> origin=<shipped|public|specialist>
   class=<green|amber|red> rule=<id|none> riskiestTool=<tool> tools=<n>
   unresolved=<n> unresolvedTools=<comma-list|none> disabled=<bool>` — one line
@@ -6115,6 +6201,12 @@ The `brand-excluded` branch closes the recurring crash-restart loop on brands th
 
 **Per-spawn signals (server.log).** Every spawn emits `pty-spawn-mcp-config servers=<N> tools=<M> bytes=<B> path=<…>` once, plus one `pty-spawn-agents-dir role=<admin|public> path=<…>` per added directory. Specialist spawns additionally emit `pty-spawn-allowlist specialist=<name> count=<N> stripped=<S> sourced-from=agent-frontmatter` where `stripped` is the count of brand-excluded tool names removed before argv emission. The diagnostic one-liner is `grep -E 'pty-spawn-mcp-config|pty-spawn-agents-dir|pty-spawn-allowlist|mcp-config-allowlist-coverage|specialist-tool-strip|boot-failed reason=' ~/.<brand>/logs/server.log | tail -50`.
 
+**Is the account's own specialist actually being used? (server.log).** An account can have its own specialists, have them registered and resolvable, and still never use them. Every reachability signal reads green through that state — the registry reconcile says a specialist CAN be reached, the roster census says it is advertised, the preference audit says whether the right one wrote an owned artefact — and none of them counts a dispatch. Skipped delegation writes no record either: the admin doing the work inline logs an ordinary success. Two signals close it, both in `server.log`.
+
+Every five minutes, one line per provisioned account, emitted including all-zero so the line's presence proves the check ran: `[specialist-census] account=<id8> declared=<n> dispatched7d=<n> bypassed7d=<n>`. `declared` counts the specialists the account authored itself, not the ones the platform ships — provisioning copies every shipped template into each account, and one of them declares roughly 130 tools, so counting every card would make the other two numbers meaningless. `dispatched7d` counts dispatches in the last seven days whose subagent `agentType` names one of those authored specialists; `bypassed7d` counts direct main-conversation calls to a tool one of them declares, native tools excluded. **`declared` above zero with `dispatched7d` at zero is the fault.** An account whose card set cannot be read emits `[specialist-census] account=<id8> op=degraded reason=<r>` and no counts at all, because a count nobody measured is worse than no count.
+
+Against that, a PreToolUse gate ([`specialist-dispatch-gate.sh`](../../admin/hooks/specialist-dispatch-gate.sh)) refuses the admin a tool one of the account's own specialists declares, and names the specialist in the refusal: `[specialist-gate] op=refuse account=<id8> tool=<t> specialist=<name>`. The caller is identified by `agent_type` in the hook envelope, which Claude Code sets inside a subagent and leaves empty in the main conversation, so the gate constrains one seat and never filters a subagent's tool surface. It fails open on an uninspectable envelope and says so with `op=degraded reason=<r>` when the card set cannot be read. Rising refusals against a flat `dispatched7d` is a distinct fault from silence: the admin is being stopped and still not delegating, which needs a change to how it is briefed rather than to the gate. The diagnostic one-liner is `grep -E '\[specialist-census\]|\[specialist-gate\]' ~/.<brand>/logs/server.log | tail -50`.
+
 **Channel follower cold-start retry.** Each `dispatchOnce`-based channel PTY session has one JSONL follower ([`platform/ui/app/lib/channel-pty-bridge/follower.ts`](../../../ui/app/lib/channel-pty-bridge/follower.ts)) reading `GET /<sessionId>/log?follow=1` and fanning each assistant `end_turn` out to the awaiting `dispatchOnce`. (WhatsApp and public webchat have since migrated to the native event channel — an MCP notification in, a `reply`-tool call out — and no longer use this follower; the remaining `dispatchOnce` channels are email and telegram. The webchat detail below is the historical record of the bug the retry fixed.) A freshly-spawned PTY has no JSONL on disk until claude flushes its first line; during that window the manager answers `202 {pending:true}`. The follower retries every `CHANNEL_PTY_FOLLOWER_RETRY_MS` (default 1000) until a 200 stream opens or `CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS` elapses. The follower is shared across channels, so that window defaults to the longest channel turn window (whatsapp's `WHATSAPP_PTY_TURN_TIMEOUT_MS`, 300000 — longer than webchat's 120000) so it never abandons a turn the caller is still awaiting. Because public sessions idle-reap, every webchat greeting is the first turn of a fresh spawn and crosses this window — before the retry, a 202 (which satisfies `res.ok`) was consumed as a single non-event line, the stream ended, and the follower died silently, timing out every public turn. The lifecycle is greppable as `follower-connect status=<code>` → `follower-retry attempt=N reason=pending` → `follower-open` → `outbound bytes=N`; `follower-give-up reason=pending-timeout` marks the JSONL never appearing. A `reject reason=turn-timeout` with no preceding `follower-open` (and no manager `log-follow-open`) for that sessionId is the signature. See `.docs/gated-public-agents.md` "Webchat turn lifecycle" for the full tag list.
 
 **Brand-process start counter.** `platform/ui/server-init.cjs` increments a persistent counter at `/tmp/server-init-<accountId>-restart.count` on every fresh start and emits `[server-init] start count=<N> account=<accountId> counter-path=<…>` to `server.log`. /tmp clears on reboot, so a clean reboot starts the count fresh; any value `>1` between operator-observed reboots means the brand process (driven by its `Requires=<brand>-claude-session-manager.service` clause) is restarting. The diagnostic one-liner is `grep '\[server-init\] start' ~/.<brand>/logs/server.log | tail -5` — the trailing `count=` value is the loop depth without counting SIGTERMs.
@@ -6674,6 +6766,16 @@ Note: passing an explicit second argument (e.g. `logs-read.sh <key> agent-stream
 
 **Diagnose if it ever recurs:** grep the per-conversation stream log for `[browser-render]`. `rendered=true domBytes=<n>` is the healthy signal. `rendered=false outcome=cdp-unreachable` means no Chromium is listening on the brand's CDP port — confirm with `curl 127.0.0.1:<cdpPort>/json/version`. Other outcomes (`navigate-failed`, `load-timeout`, `evaluate-failed`) name the failed CDP step.
 
+## Stylesheet text is visible on a client document, or a styled box has lost its rules
+
+**Symptom:** A client-facing HTML document shows raw CSS as text on the page, usually above the header, and a box further down the same document renders unstyled (no border, no padding). Both are one fault, not two.
+
+**Cause:** A `<style>` element opened inside another one. HTML parses style content as raw text, so the two do not nest: the first `</style>` closes the outer element, everything after it becomes body content and renders as visible text, and the rule immediately after the stray opener is eaten as part of an invalid selector.
+
+**Resolution:** Delete the stray opener. Put the block in the body as its own `<style>` element, or merge its rules into the one already open. If the document is deployed, redeploy it, then confirm the rule is present in the parsed stylesheet — a changed byte count is not proof.
+
+**Diagnose:** `grep -F '[html-structure-census]' ~/.<brand>/logs/server.log | tail -1` reports `accounts=`, `documents=` and `malformed=` from the last standing tick, and each malformed document has its own `op=malformed account=<id8> file="<path>" line=<n>` line naming the stray opener. The summary is emitted on every run including a zero count, so no line at all means the walk is broken rather than the install being clean, and `documents=0` means the same. A write that would produce the shape is refused before it lands, logging `[html-structure-gate] op=refuse` to the same file.
+
 ## First user-domain write rejected by `[graph-write-gate] reject reason=no-admin-user`
 
 **Symptom:** Admin chat reports "couldn't save that — set up your business profile first" or `[graph-write-gate] reject reason=no-admin-user` appears in `server.log` on the operator's first non-bootstrap write (a website, service, opening hours, etc.). Reproduces on Minimal-onboarded installs from before the seed-stamping fix shipped.

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,24 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-07 (0.1.574)
+
+- An answer meant for you now reaches every channel you have live, not just the one you asked from. That had never actually worked, and nothing reported it.
+- A document sent to a customer is now checked before it leaves. A malformed one could reach the customer with nothing looking at it, and the page-two header check was asserting against something the document never carries, so an oversized or missing header on later pages gave no signal at all.
+- The agents list now describes the specialist that actually runs. It was showing you the authored copy while dispatch used a different one, so what you read and what ran could differ.
+- An account whose specialists are present but never actually used is now detected and reported, rather than looking healthy indefinitely.
+- Email sent through Outlook can now be accounted for. A draft could leave your Drafts folder without the assistant ever sending it, and no surface could say who did; each request is now recorded so the answer comes from a record rather than an inference.
+
+## 2026-08-07 (0.1.573)
+
+- One piece of the platform now sends every answer to every channel, instead of each channel deciding for itself. A standing check compares what the conversation record holds against what was actually sent, so a missing message is reported rather than noticed.
+- A healthy conversation sitting idle is no longer mistaken for a stuck one and shut down. A recovered conversation now also re-sends the answer it was holding.
+- Your second message in an admin webchat reaches the conversation you are already in. It was being addressed to a name the running conversation had never subscribed to, so it could report a delivery failure and then arrive twice.
+- A file the assistant sends you now opens. The download link was refused for anyone outside the account that produced it, so the link returned a not-found.
+- Telegram now supports far more of what the service can do, rather than the four operations it exposed before.
+- A routine that is switched off by a check now stops waking the assistant, and the check that woke it is recorded. The audits behind those checks now report somewhere that is actually read.
+- Sending an email draft no longer reports success when the step before it was refused, which could send the same message twice.
+
 ## 2026-08-07 (0.1.572)
 
 - A new dispatch planner in the admin gives the office a week-grid view of each worker's day with per-day state and standing divergence checks.