@rubytech/create-maxy-code 0.1.573 → 0.1.575

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,34 @@ 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. They say who a
+sender is. They do not decide where an answer goes: an answer always goes back
+to the door the message arrived on and nowhere else.
+
+`phone` is the E.164 number, identifying a WhatsApp sender as this person.
+`telegram` is the chat id, matched exactly, doing the same for a Telegram
+sender. They are not interchangeable, and a person messaging from both channels
+needs both set to be recognised on 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 sender is not recognised as this admin. These
+lines in `server.log` name it:
+
+| Line | Means |
+|---|---|
+| `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | this sender resolves to no admin |
+| `[channel-fanout] op=fan-out reached=… notReached=…` | whether the door that wrote 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 +61,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 Maxy 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:5b9f6de800b201bf45e5d433a707987b4d09c6fb7d552240158afb2f73a3600f
+content-hash: sha256:1ec8c1bb3bfb2272908989878b5265b79f6c79ea5ada31153c846a3dd6214b40
 brand: maxy-code
 product-name: Maxy
 ---
@@ -730,22 +730,44 @@ No status, job type, qualification, checklist, SLA target or operator noun appea
 A test walks every source file and fails if any string from either shipped fixture config appears in
 it.
 
-## The ten tools
+## The sixteen tools
 
 | Tool | Does | Refuses when |
 |---|---|---|
 | `dispatch-config-get` | Returns the vocabulary, statuses, transitions, job types, roster, checklists and the config audit | no config |
+| `dispatch-site-upsert` | Creates a site under its customer, or gives an existing site its street, town and postcode | a new site with no `customerId`, `name` or `region`; a customer that does not exist; a region outside East/North/South/West; some but not all three address fields |
+| `dispatch-intake-draft` | Holds an inbound request as a draft, storing the fields that resolved and naming the required ones that did not | neither the site nor the customer exists, so there is nothing to attach the draft to |
+| `dispatch-intake-decide` | Approves a draft into a job through the `dispatch-job-create` path, or rejects it with a reason and keeps it | draft unknown; already decided; rejecting with no reason; approving while a required field is still missing |
+| `dispatch-intake-list` | The undecided queue oldest first, or drafts already decided when a verdict is named | — |
 | `dispatch-job-create` | Raises a job at a site for a customer, in the account's first job status, with `slaTargetAt` computed from the type | unknown job type; site or customer does not exist |
 | `dispatch-job-get` | One job with every visit, its times, who attended and what was recorded | job not on this account |
 | `dispatch-job-list` | Jobs filtered by status, type, worker, date window, or narrowed to never-allocated. `overdue` computed on every read | status not declared |
-| `dispatch-allocate-candidates` | Who could take this job in this window, with clashes shown and exclusions named | job unknown, untyped, or typed to something no longer declared |
+| `dispatch-allocate-candidates` | Who could take this job in this window, with clashes shown, exclusions named, and an estimated travel time from each worker's previous visit that day | job unknown, untyped, or typed to something no longer declared |
 | `dispatch-allocate` | Creates the visit, attends it, moves the job along its own edge, attaches a vehicle | worker not on the roster; worker lacks the qualification; vehicle passed while `vehicles.enabled` is false; no `:Person:Engineer` node for the workerId |
 | `dispatch-visit-status-set` | Moves a visit; closes the job when its last visit reaches a terminal status | status not declared; transition not in the edge list; a required record missing |
 | `dispatch-visit-record` | Note, media reference, fitted part, checklist item, signature, arrival | visit unknown; nothing supplied to record |
 | `dispatch-site-history` | Every visit at one site, newest first, with notes | — |
 | `dispatch-day` | One day: every worker with the visits they hold, plus jobs nobody has been sent to | — |
+| `dispatch-notify-worker` | Sends the worker attending a visit its card: one button per move this account allows from where the visit is now, plus a button opening the job sheet inside Telegram | visit unknown or unallocated; worker not on the roster; worker carries no `telegramUserId`; no bot registered; origin is not https |
+| `dispatch-site-location-set` | Gives a site a latitude and longitude, and optionally its own arrival radius in metres | site not on this account; coordinates out of range; radius zero or negative |
 
-All ten are `adminAllowlist: true`, `publicAllowlist: false`.
+All sixteen are `adminAllowlist: true`, `publicAllowlist: false`.
+
+## A request is a draft before it is a job
+
+An inbound request becomes an `:IntakeDraft`, never a `:Job` with a flag — a draft that is a `:Job`
+shows up in `dispatch-job-list`, in the census `jobs=` count and in the planner. A value that names
+nothing on this account counts as missing exactly like an omitted one, so there is one list of gaps
+to act on rather than two vocabularies to reconcile.
+
+A draft must resolve at least one of its site or its customer, because the graph write path rejects
+a node with no adjacency and this plugin creates neither. A request naming neither is refused with
+both fields named.
+
+Approval runs through the same write path `dispatch-job-create` uses, so the opening status and the
+SLA target come from the account's config and `op=job-create` still appears. A rejection stores its
+reason and keeps the draft. A decision is final; a second one is refused rather than raising a
+duplicate job.
 
 ## Legality is data
 
@@ -767,7 +789,19 @@ Only a missing qualification excludes a worker, and every exclusion is named:
 with the clash shown. Double-booking is the office's decision, and a tool that drops the busy option
 makes that decision for them with no trace.
 
-There is no travel-time estimate.
+## How far each candidate has to come
+
+Every offered candidate carries `travelMinutes` from their previous visit that day to this job's
+site. It is a **straight-line** figure over an assumed road speed, named in `travelProvider`, so it
+is a lower bound on the drive and never a route: an estuary or a one-way system costs minutes it
+cannot see. Set a site's coordinates with `dispatch-site-location-set` to make it measurable.
+
+A candidate with no estimate carries no `travelMinutes` at all, plus a `travelReason` saying why —
+the worker has nothing earlier that day, or a site has no coordinates, named so you know which one
+to fix. There is no zero and no null, because either would read as a measurement.
+
+A provider that fails never shortens the list. The office sees the same people it would have seen,
+each carrying the reason instead of a number.
 
 ## Arrival is two properties
 
@@ -776,18 +810,59 @@ either never clears the other. An observation with no press is stored and flagge
 is what somebody said; an observed one is what was measured, and a single `arrivedAt` cannot show
 them disagreeing.
 
+## The card in the worker's chat
+
+A worker does not have to open anything to move a job along. `dispatch-notify-worker` sends the
+visit as a card in his Telegram chat, carrying one button per move this account allows from where the
+visit is now, and one button that opens the full job sheet inside Telegram. Press a button and the
+visit moves; the card redraws itself with whatever is legal next.
+
+Two things have to be true before a card can go anywhere. The worker's entry in
+`dispatch/config.json` needs his numeric `telegramUserId`, the same one the job sheet signs him in
+with. And the account needs an admin Telegram bot registered, which `telegram-setup` does.
+
+A button that is out of date is refused, not applied. If the office moved the visit on while the
+card sat on his phone, pressing it tells him what the button was for and what the visit is now, and
+redraws the card. Nothing is applied twice and nothing is applied out of order.
+
+If he shares his live location, and the site has coordinates, arriving inside the site's radius
+records the arrival independently of anything he pressed. Both times are kept. That is the whole
+point: what somebody said and what was measured can then disagree, and the disagreement is visible.
+A site gets its coordinates from `dispatch-site-location-set`; without them the geofence cannot fire
+and `sitesWithoutCoords=` counts how many are still unplaced. The radius is the site's own if it has
+one, otherwise the account's `vehicles.defaultGeofenceRadiusM`; with neither, nothing is recorded,
+because a distance with nothing to compare it against cannot say whether anybody arrived.
+
+A voice note becomes that visit's note, transcribed. A photo becomes its media. Both need exactly
+one visit open for that worker: with none, or with more than one, the message stays in the chat and
+he is told which visit to open, because filing a photograph against the wrong job silently is worse
+than asking.
+
 ## The standing checks
 
-Six failure modes emit no event, because no action occurs: a job created and never allocated, a job
-past its SLA target, a status no transition reaches, a job type no worker is qualified for, a worker
-with no qualification, and visits closing hours after the work ended.
+Eight failure modes emit no event, because no action occurs: a draft nobody decided on, a job
+created and never allocated, a job past its SLA target, a status no transition reaches, a job
+type no worker is qualified for, a worker with no qualification, visits closing hours after the
+work ended, and a card sent to a worker's phone that never arrived.
+
+The draft is the sharpest of them. Nothing was created so there are no write logs, nothing was
+refused so there are no rejection logs, and the requester never got an answer. It is byte-identical
+to a quiet morning until the census counts it.
 
 - `[dispatch-census]`, per account, every 15 minutes: `jobs= unallocated= oldestUnallocatedAgeH=
-  overdue= visitsOpen= visitsOpenOver24h=`
+  overdue= visitsOpen= visitsOpenOver24h= intakeUnreviewed= oldestIntakeAgeH=`
 - `[dispatch-config-audit]`, on config load and each tick: `statuses= unreachable= terminal=
   jobTypes= typesWithNoQualifiedWorker= workersWithNoQualification=`
 - `[dispatch-record-census]`, daily: `closedVisits= withNote= withMedia= medianRecordLagS=
   p90RecordLagS=`
+- `[dispatch-tg-census]`, per account, every 15 minutes: `dispatchedToday= acknowledged=
+  unacknowledged= oldestUnackMin= keyboardsLive= keyboardsOnClosedVisits= callbacksToday=
+  callbacksFailed= voiceAwaitingTranscription= sitesWithoutCoords=`
+
+A card that never reached a worker's phone is the seventh failure mode that emits nothing at all.
+Nothing is logged because nothing happened, so only counting cards sent against cards pressed can
+see it. `oldestUnackMin` climbing across ticks is a phone that is off, out of signal, or a worker
+who has stopped looking.
 
 They run in the UI server, not in the plugin, because a plugin only runs when somebody calls it.
 Accounts without a dispatch config are skipped silently.
@@ -814,11 +889,13 @@ Europe/London visit near local midnight for the whole of British Summer Time, so
 derives boundaries in the account's own timezone. And `dispatch-job-list` caps its rows, so the
 planner takes its counts from an aggregate instead of counting what it was given.
 
-It also names a defect it cannot fix. `dispatch-allocate` stores `startDate` exactly as the caller
-passed it (`allocate.ts:186`) while normalising `endDate` (`allocate.ts:51`). The window compare is
-lexical, so a start carrying a non-UTC offset reads correctly under GMT and an hour out under
-British Summer Time. The planner logs `op=nonzulu-start` with the offending visit ids; correcting
-it belongs at the writer.
+The window compare is lexical, so an instant carrying a non-UTC offset reads correctly under GMT and
+an hour out under British Summer Time. It is fixed at the writer, the only place it can be fixed:
+`dispatch-allocate` normalises `startDate` and `endDate` through `platform/lib/canonical-instant`,
+the same definition the scheduling writers use, and refuses a value it cannot convert. Stored rows
+converge on install. The planner still logs `op=nonzulu-start` with the offending visit ids, and
+`[dispatch-census]` carries `nonCanonicalInstants` every sweep, so a regression is visible with or
+without a browser open.
 
 Full detail: [`.docs/dispatch-planner.md`](../../../.docs/dispatch-planner.md).
 
@@ -854,11 +931,13 @@ Full detail: [`.docs/dispatch-field-app.md`](../../../.docs/dispatch-field-app.m
 ## Diagnostic path
 
 ```
-journalctl --user -u <brand>-* | grep -E '\[dispatch\]|\[dispatch-census\]|\[dispatch-config-audit\]|\[dispatch-record-census\]|\[dispatch-field\]|\[dispatch-field-census\]'
+journalctl --user -u <brand>-* | grep -E '\[dispatch\]|\[dispatch-census\]|\[dispatch-config-audit\]|\[dispatch-record-census\]|\[dispatch-field\]|\[dispatch-field-census\]|\[dispatch-tg\]|\[dispatch-tg-census\]'
 ```
 
 Then filter by `jobId=` for one job's lifeline, `op=transition-refused` to audit rejected writes, or
-`exclusions=` to see why allocation offered whom.
+`exclusions=` to see why allocation offered whom. For the card path, `updateId=` follows one press
+end to end, `visitId=` follows one visit's whole field record, and `op=unbound-inbound` finds the
+messages that reached no visit.
 
 ---
 # Install Overview
@@ -1946,19 +2025,11 @@ 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.
 
 ```
 [channel-fanout] op=fan-out reached=… notReached=… segments=… messageId=… sessionId=…
@@ -1969,6 +2040,30 @@ JSONL and the real follower.
 census prints every cycle, including when the counts agree: an absent line means
 the census stopped, never that delivery is healthy.
 
+## Which door an answer reaches
+
+The door the message arrived on, and no other. A question asked on WhatsApp is
+answered on WhatsApp; one asked on Telegram is answered on Telegram. The browser
+reader is not a door at all: it tails the session record the answer was taken
+from, so it shows the conversation without anything being sent to it.
+
+Answers used to also reach the person's other bound channel. That was removed:
+only the answer text travelled, never the question, so the second app showed a
+reply with nothing above it. The same conversation already follows you to
+another device through WhatsApp Web and Telegram Web, each for its own channel.
+
+The two lines that name a delivery failure:
+
+| Line | Means |
+|---|---|
+| `[channel-fanout] op=no-target origin=… reason=origin-not-live` | the door holds no live target for this key |
+| `[channel-fanout] op=no-target origin=telegram key=… accountId=none reason=no-account` | no account on this install owns the bot in that key |
+
+`[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
@@ -2877,9 +2972,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 Maxy 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 |
 |-------|------------|
@@ -2931,6 +3036,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 Maxy 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
 
@@ -2947,6 +3059,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.
@@ -4135,24 +4260,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.
@@ -4322,7 +4466,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. |
@@ -4368,11 +4512,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
@@ -4399,13 +4545,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
@@ -6106,6 +6271,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.
@@ -6665,6 +6836,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,22 @@ 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-08 (0.1.575)
+
+- **Reverses one change from 0.1.574.** An answer now stays on the channel you asked from, rather than also being copied to your other channels. The copy arrived as a reply with no question above it, because only the answer travelled and not what you had asked; a WhatsApp question turned up in Telegram as a bare statement. Being reachable on more than one device is already handled per channel, so the copy was removed rather than completed.
+- You no longer get told a tool call is blocked when it is simply taking a while. Every long-running call was being reported as blocked and pushed to your channel.
+- Field and dispatch work is now usable end to end: an incoming request can be reviewed into a job instead of sitting in an unqueued pile, a site carries the address the worker needs to find it, allocation shows the travel time from the previous job, two workers on one visit are no longer indistinguishable from two separate visits, and pressing a button in Telegram now acts on the visit rather than sending a typed message.
+- A visit's start time is stored consistently, so a comparison against a time window is no longer an hour out during British Summer Time.
+- Two safeguards closed: a file the assistant was refused permission to copy across accounts could still land minutes later by another route with nothing recording it, and the outbound check that strips private paths did not know about the media directory now served on the public door.
+
+## 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.