@rubytech/create-maxy-code 0.1.573 → 0.1.574

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/package.json +1 -1
  2. package/payload/platform/lib/admins-write/__tests__/index.test.ts +97 -0
  3. package/payload/platform/lib/admins-write/dist/index.d.ts +12 -0
  4. package/payload/platform/lib/admins-write/dist/index.d.ts.map +1 -1
  5. package/payload/platform/lib/admins-write/dist/index.js +27 -5
  6. package/payload/platform/lib/admins-write/dist/index.js.map +1 -1
  7. package/payload/platform/lib/admins-write/src/index.ts +35 -5
  8. package/payload/platform/lib/admins-write/vitest.config.ts +14 -0
  9. package/payload/platform/lib/dispatch-read/dist/session.d.ts.map +1 -1
  10. package/payload/platform/lib/dispatch-read/dist/session.js +19 -4
  11. package/payload/platform/lib/dispatch-read/dist/session.js.map +1 -1
  12. package/payload/platform/lib/dispatch-read/src/__tests__/session.test.ts +91 -0
  13. package/payload/platform/lib/dispatch-read/src/session.ts +25 -6
  14. package/payload/platform/plugins/admin/.claude-plugin/plugin.json +1 -1
  15. package/payload/platform/plugins/admin/PLUGIN.md +8 -3
  16. package/payload/platform/plugins/admin/hooks/__tests__/html-structure-gate.test.sh +264 -0
  17. package/payload/platform/plugins/admin/hooks/__tests__/quote-render-pdf-conformance.test.sh +122 -24
  18. package/payload/platform/plugins/admin/hooks/__tests__/specialist-dispatch-gate.test.sh +158 -0
  19. package/payload/platform/plugins/admin/hooks/html-structure-gate.sh +165 -0
  20. package/payload/platform/plugins/admin/hooks/quote-render-pdf-conformance.sh +111 -19
  21. package/payload/platform/plugins/admin/hooks/specialist-dispatch-gate.sh +159 -0
  22. package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.d.ts +27 -0
  23. package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.d.ts.map +1 -0
  24. package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.js +29 -0
  25. package/payload/platform/plugins/admin/mcp/dist/admin-bind-classify.js.map +1 -0
  26. package/payload/platform/plugins/admin/mcp/dist/binding-validate.d.ts +11 -0
  27. package/payload/platform/plugins/admin/mcp/dist/binding-validate.d.ts.map +1 -0
  28. package/payload/platform/plugins/admin/mcp/dist/binding-validate.js +20 -0
  29. package/payload/platform/plugins/admin/mcp/dist/binding-validate.js.map +1 -0
  30. package/payload/platform/plugins/admin/mcp/dist/index.js +133 -1
  31. package/payload/platform/plugins/admin/mcp/dist/index.js.map +1 -1
  32. package/payload/platform/plugins/admin/skills/admin-user-management/SKILL.md +32 -2
  33. package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md +157 -46
  34. package/payload/platform/plugins/admin/skills/whats-new/SKILL.md +8 -0
  35. package/payload/platform/plugins/docs/references/admin-ui.md +71 -31
  36. package/payload/platform/plugins/docs/references/channel-wake-and-prompt.md +38 -13
  37. package/payload/platform/plugins/docs/references/internals.md +6 -0
  38. package/payload/platform/plugins/docs/references/outlook-guide.md +31 -1
  39. package/payload/platform/plugins/docs/references/troubleshooting.md +10 -0
  40. package/payload/platform/plugins/outlook/PLUGIN.md +3 -1
  41. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger-write-sites.test.d.ts +2 -0
  42. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger-write-sites.test.d.ts.map +1 -0
  43. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger-write-sites.test.js +177 -0
  44. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger-write-sites.test.js.map +1 -0
  45. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger.test.d.ts +2 -0
  46. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger.test.d.ts.map +1 -0
  47. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger.test.js +130 -0
  48. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-ledger.test.js.map +1 -0
  49. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-reconcile.test.d.ts +2 -0
  50. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-reconcile.test.d.ts.map +1 -0
  51. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-reconcile.test.js +162 -0
  52. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-reconcile.test.js.map +1 -0
  53. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-state-fields.test.d.ts +2 -0
  54. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-state-fields.test.d.ts.map +1 -0
  55. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-state-fields.test.js +168 -0
  56. package/payload/platform/plugins/outlook/mcp/dist/__tests__/draft-state-fields.test.js.map +1 -0
  57. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-ledger.d.ts +64 -0
  58. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-ledger.d.ts.map +1 -0
  59. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-ledger.js +110 -0
  60. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-ledger.js.map +1 -0
  61. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-reconcile.d.ts +119 -0
  62. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-reconcile.d.ts.map +1 -0
  63. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-reconcile.js +0 -0
  64. package/payload/platform/plugins/outlook/mcp/dist/lib/draft-reconcile.js.map +1 -0
  65. package/payload/platform/plugins/outlook/mcp/dist/scripts/draft-reconcile.d.ts +8 -0
  66. package/payload/platform/plugins/outlook/mcp/dist/scripts/draft-reconcile.d.ts.map +1 -0
  67. package/payload/platform/plugins/outlook/mcp/dist/scripts/draft-reconcile.js +247 -0
  68. package/payload/platform/plugins/outlook/mcp/dist/scripts/draft-reconcile.js.map +1 -0
  69. package/payload/platform/plugins/outlook/mcp/dist/tools/draft-send.d.ts.map +1 -1
  70. package/payload/platform/plugins/outlook/mcp/dist/tools/draft-send.js +10 -0
  71. package/payload/platform/plugins/outlook/mcp/dist/tools/draft-send.js.map +1 -1
  72. package/payload/platform/plugins/outlook/mcp/dist/tools/draft.d.ts.map +1 -1
  73. package/payload/platform/plugins/outlook/mcp/dist/tools/draft.js +21 -0
  74. package/payload/platform/plugins/outlook/mcp/dist/tools/draft.js.map +1 -1
  75. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-fetch-body.d.ts +16 -0
  76. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-fetch-body.d.ts.map +1 -1
  77. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-fetch-body.js +5 -1
  78. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-fetch-body.js.map +1 -1
  79. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-list.d.ts +4 -0
  80. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-list.d.ts.map +1 -1
  81. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-list.js +2 -1
  82. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-list.js.map +1 -1
  83. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-reply.d.ts.map +1 -1
  84. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-reply.js +24 -0
  85. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-reply.js.map +1 -1
  86. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-search.d.ts.map +1 -1
  87. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-search.js +2 -1
  88. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-search.js.map +1 -1
  89. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-send.d.ts.map +1 -1
  90. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-send.js +29 -0
  91. package/payload/platform/plugins/outlook/mcp/dist/tools/mail-send.js.map +1 -1
  92. package/payload/platform/plugins/scheduling/mcp/dist/__tests__/draft-reconcile-throttle.test.d.ts +2 -0
  93. package/payload/platform/plugins/scheduling/mcp/dist/__tests__/draft-reconcile-throttle.test.d.ts.map +1 -0
  94. package/payload/platform/plugins/scheduling/mcp/dist/__tests__/draft-reconcile-throttle.test.js +21 -0
  95. package/payload/platform/plugins/scheduling/mcp/dist/__tests__/draft-reconcile-throttle.test.js.map +1 -0
  96. package/payload/platform/plugins/scheduling/mcp/dist/lib/draft-reconcile-throttle.d.ts +13 -0
  97. package/payload/platform/plugins/scheduling/mcp/dist/lib/draft-reconcile-throttle.d.ts.map +1 -0
  98. package/payload/platform/plugins/scheduling/mcp/dist/lib/draft-reconcile-throttle.js +10 -0
  99. package/payload/platform/plugins/scheduling/mcp/dist/lib/draft-reconcile-throttle.js.map +1 -0
  100. package/payload/platform/plugins/scheduling/mcp/dist/scripts/check-due-events.js +54 -0
  101. package/payload/platform/plugins/scheduling/mcp/dist/scripts/check-due-events.js.map +1 -1
  102. package/payload/platform/services/claude-session-manager/dist/authored-specialist-tools.d.ts +32 -0
  103. package/payload/platform/services/claude-session-manager/dist/authored-specialist-tools.d.ts.map +1 -0
  104. package/payload/platform/services/claude-session-manager/dist/authored-specialist-tools.js +144 -0
  105. package/payload/platform/services/claude-session-manager/dist/authored-specialist-tools.js.map +1 -0
  106. package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.d.ts.map +1 -1
  107. package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.js +1 -0
  108. package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.js.map +1 -1
  109. package/payload/platform/services/claude-session-manager/dist/html-structure-census.d.ts +44 -0
  110. package/payload/platform/services/claude-session-manager/dist/html-structure-census.d.ts.map +1 -0
  111. package/payload/platform/services/claude-session-manager/dist/html-structure-census.js +185 -0
  112. package/payload/platform/services/claude-session-manager/dist/html-structure-census.js.map +1 -0
  113. package/payload/platform/services/claude-session-manager/dist/index.js +125 -0
  114. package/payload/platform/services/claude-session-manager/dist/index.js.map +1 -1
  115. package/payload/platform/services/claude-session-manager/dist/quote-delivery-reconcile.d.ts.map +1 -1
  116. package/payload/platform/services/claude-session-manager/dist/quote-delivery-reconcile.js +7 -0
  117. package/payload/platform/services/claude-session-manager/dist/quote-delivery-reconcile.js.map +1 -1
  118. package/payload/platform/services/claude-session-manager/dist/quote-print-census.d.ts +42 -0
  119. package/payload/platform/services/claude-session-manager/dist/quote-print-census.d.ts.map +1 -0
  120. package/payload/platform/services/claude-session-manager/dist/quote-print-census.js +254 -0
  121. package/payload/platform/services/claude-session-manager/dist/quote-print-census.js.map +1 -0
  122. package/payload/platform/services/claude-session-manager/dist/specialist-census.d.ts +92 -0
  123. package/payload/platform/services/claude-session-manager/dist/specialist-census.d.ts.map +1 -0
  124. package/payload/platform/services/claude-session-manager/dist/specialist-census.js +227 -0
  125. package/payload/platform/services/claude-session-manager/dist/specialist-census.js.map +1 -0
  126. package/payload/platform/templates/account-settings.json +8 -4
  127. package/payload/server/server.js +465 -361
@@ -13,7 +13,8 @@ This skill manages who has admin access to this account. It wraps six MCP tools
13
13
 
14
14
  | Tool | Purpose |
15
15
  |---|---|
16
- | `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. |
16
+ | `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. |
17
+ | `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. |
17
18
  | `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. |
18
19
  | `admin-list` | List all admins on this account with names and roles. |
19
20
  | `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
24
25
 
25
26
  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.
26
27
 
28
+ ## Channel bindings decide whether an answer reaches a second channel
29
+
30
+ An admin's `users.json` entry carries two optional bindings, and they are what
31
+ lets one answer reach every channel that person holds rather than only the one
32
+ the message arrived on.
33
+
34
+ `phone` is the E.164 number. It identifies a WhatsApp sender as this person, and
35
+ it is also the address used to reach them on WhatsApp when a turn arrives
36
+ somewhere else. `telegram` is the chat id, matched exactly, doing the same two
37
+ jobs for Telegram. They are not interchangeable, and two-way reach needs both.
38
+
39
+ `account.json` `whatsapp.adminPhones` is a different thing: an allowlist saying
40
+ a number may reach the admin agent. It grants access; it does not say whose
41
+ number it is, which is why adding a phone there never binds anyone.
42
+
43
+ When a binding is missing, the failure is silent to the person messaging. These
44
+ lines in `server.log` name it:
45
+
46
+ | Line | Means |
47
+ |---|---|
48
+ | `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | this sender resolves to no admin, so no second door is looked for |
49
+ | `[channel-fanout] op=no-target origin=… reason=no-admin-user` | the same fact, at the fan-out |
50
+ | `[channel-fanout] op=fan-out reached=… notReached=…` | which doors actually received the answer |
51
+
52
+ A Telegram bot owned by a `role:'client'` sub-account can never resolve an
53
+ admin: both resolvers return null on a client account before reading any chat
54
+ id. Setting `telegram` will not help there; the bot has to live on the house
55
+ account.
56
+
27
57
  ## The three-store invariant
28
58
 
29
59
  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:
32
62
  2. `users.json`: device-level PIN authentication. This is the source of truth at login.
33
63
  3. The Neo4j graph: `:AdminUser` + `:Person` + `OWNS` + `ADMIN_OF` edges. Display and graph identity.
34
64
 
35
- `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.
65
+ `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.
36
66
 
37
67
  ## Never write `account.json` directly
38
68
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: platform-architecture
3
3
  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.
4
- content-hash: sha256:5b9f6de800b201bf45e5d433a707987b4d09c6fb7d552240158afb2f73a3600f
4
+ content-hash: sha256:70424aa650da5b5537cd193b383cacce08d90d36685af88044390c6e5efe6262
5
5
  brand: maxy-code
6
6
  product-name: Maxy
7
7
  ---
@@ -1946,19 +1946,11 @@ defect. Turns that answered no inbound — subagent side-chains, turns driven fr
1946
1946
  claude.ai — are deliberately outside that set: the credit guards are what keep
1947
1947
  them out of a customer's chat.
1948
1948
 
1949
- Each door's `src/parity.test.ts` asserts the contract end to end against a real
1950
- JSONL and the real follower.
1951
-
1952
- **Six discard sites, each now logged.** A follower outcome is dropped at:
1953
-
1954
- | File | Guard | `reason=` |
1955
- |---|---|---|
1956
- | `telegram-channel/src/server.ts:241` | `pendingTurns <= 0` | `no-credit` |
1957
- | `webchat-channel/src/server.ts:378` | `pendingTurns <= 0` | `no-credit` |
1958
- | `whatsapp-channel/src/server.ts:481` | `pendingTurns <= 0` | `no-credit` |
1959
- | `whatsapp-channel/src/server.ts:489` | `consumedInbounds <= 0` | `no-consumed-inbound` |
1960
- | `whatsapp-channel/src/server.ts:617` | `pendingTurns <= 0` (2nd follower) | `no-credit` |
1961
- | `whatsapp-channel/src/server.ts:620` | `consumedInbounds <= 0` (2nd follower) | `no-consumed-inbound` |
1949
+ **Discard sites.** The WhatsApp and Telegram followers and their credit ledgers
1950
+ were removed, so those two doors now have none: one emitter reads the JSONL and
1951
+ the fan-out decides where an answer goes. Only webchat still carries credit
1952
+ guards, in `webchat-channel/src/server.ts`, and `src/parity.test.ts` survives
1953
+ for that door alone.
1962
1954
 
1963
1955
  ```
1964
1956
  [channel-fanout] op=fan-out reached=… notReached=… segments=… messageId=… sessionId=…
@@ -1969,6 +1961,39 @@ JSONL and the real follower.
1969
1961
  census prints every cycle, including when the counts agree: an absent line means
1970
1962
  the census stopped, never that delivery is healthy.
1971
1963
 
1964
+ ## What a second door actually requires
1965
+
1966
+ Reaching a door other than the one the message arrived on needs two facts.
1967
+
1968
+ **The person must be resolvable from the turn's sender.** That resolution reads
1969
+ one place: the admin's `users.json` entry. `phone` (E.164) identifies a WhatsApp
1970
+ sender; `telegram` (the chat id, matched exactly) identifies a Telegram sender.
1971
+ `account.json` `whatsapp.adminPhones` is a different store with a different job:
1972
+ it says a number may reach the admin agent, not whose number it is, which is why
1973
+ adding a phone there binds nobody. Set the bindings with `admin-bind`, or at
1974
+ creation with `admin-add`'s `phone` and `telegram`.
1975
+
1976
+ **The other door must hold a live target for that person.** `phone` addresses
1977
+ WhatsApp when a Telegram turn wants to reach it, and `telegram` addresses
1978
+ Telegram from a WhatsApp turn. Two-way reach needs both fields, not one.
1979
+
1980
+ The three lines that name each failure:
1981
+
1982
+ | Line | Means |
1983
+ |---|---|
1984
+ | `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | no binding, so no second door is even looked for |
1985
+ | `[channel-fanout] op=no-target origin=… reason=no-admin-user` | the same fact, observed at the fan-out |
1986
+ | `[channel-fanout] op=no-target origin=… reason=origin-not-live` | the door holds no live target for this key |
1987
+
1988
+ A Telegram bot owned by a `role:'client'` sub-account can never resolve an
1989
+ admin: both resolvers return null on a client account before reading any chat
1990
+ id. No binding fixes that; the bot has to live on the house account.
1991
+
1992
+ `[whatsapp-account-scope] op=non-uuid-account caller=fan-out` means the fan-out
1993
+ was handed a Baileys credential dirname where a platform UUID belongs. That is
1994
+ the defect that stranded a live admin answer, and the line exists so the next
1995
+ occurrence announces itself instead of being inferred from a silent miss.
1996
+
1972
1997
  **Read them in `server.log`.** Both are emitted by the ui-server, which now owns
1973
1998
  the one emitter between the session JSONL and every channel. The per-door
1974
1999
  `op=turn-drop` and `op=census` lines that used to sit in
@@ -2877,9 +2902,19 @@ Mail only: calendar and contacts tools refuse on a shared mailbox and say so. If
2877
2902
 
2878
2903
  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.
2879
2904
 
2905
+ ## What an empty Drafts folder does not prove
2906
+
2907
+ 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.
2908
+
2909
+ 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.
2910
+
2911
+ 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.
2912
+
2913
+ 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.
2914
+
2880
2915
  ## Observability
2881
2916
 
2882
- All log lines start with `[outlook-mcp]` and write to `server.log`. They are key=value, account-scoped:
2917
+ 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:
2883
2918
 
2884
2919
  | Event | Line shape |
2885
2920
  |-------|------------|
@@ -2931,6 +2966,13 @@ All log lines start with `[outlook-mcp]` and write to `server.log`. They are key
2931
2966
  | Draft-send request | `draft-send-request account=<id> id=<draftId>` |
2932
2967
  | Draft sent | `draft-sent account=<id> id=<draftId> status=202` |
2933
2968
  | Draft-send failed | `draft-send-failed account=<id> id=<draftId> error=<msg>` |
2969
+ | 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 |
2970
+ | 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 |
2971
+ | 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`** |
2972
+ | 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** |
2973
+ | Reconcile pruned | `draft-reconcile-pruned accounts=<N> removed=<N> kept=<N>` |
2974
+ | Reconcile skipped | `draft-reconcile-skipped reason=no-vendor-app` — this brand ships no Outlook app; distinct from "did not run" |
2975
+ | Reconcile could not run | `draft-reconcile-failed error=<msg>` — exit 1 |
2934
2976
 
2935
2977
  ## Diagnostic paths
2936
2978
 
@@ -2947,6 +2989,19 @@ grep -E "^\[outlook-mcp\] (mail-reply|draft-created)" ~/.maxy/logs/server.log \
2947
2989
  | grep -E "threaded=true|op=reply" | grep -E "convId=(null)?( |$)" | head
2948
2990
  ```
2949
2991
 
2992
+ ```bash
2993
+ # One draft's whole lifeline: created, then a verdict per hourly pass.
2994
+ grep -E "op=draft-ledger|op=draft-reconcile" ~/.maxy/logs/check-due-events.log | grep "draftId=<id>"
2995
+
2996
+ # Did the reconcile stop? An absent census IS the failure signal.
2997
+ grep -c "op=draft-reconcile-census" ~/.maxy/logs/check-due-events.log
2998
+
2999
+ # Confirm a sent-not-by-maxy: this must be EMPTY for the window in question.
3000
+ grep -E "op=request tool=outlook-(draft-send|mail-send|mail-reply)" ~/.maxy/logs/mcp-outlook-*.log
3001
+ ```
3002
+
3003
+ 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`.
3004
+
2950
3005
  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.
2951
3006
 
2952
3007
  Latency triage: `mail-list count=0 elapsedMs<200` consistent → permissions issue; `elapsedMs > 5000` → Graph slowness or DNS.
@@ -4135,24 +4190,43 @@ both `kind: 'specialist'` and differ only by origin.
4135
4190
  repair, and it is not what runs unattended: an agent runs only when something
4136
4191
  dispatches it, an inbound message is operator-initiated, so the only autonomous
4137
4192
  path is the scheduler. The modal says so and points at the routines instead.
4138
- **A file in the LIVE directory whose name also exists under
4139
- `<accountDir>/plugins/*/agents/` is excluded from this set.** `agent-builder`
4140
- copies the authored file into `specialists/agents/` because presence there is
4141
- what makes an agent dispatchable, so the live directory says nothing about who
4142
- wrote the agent and every activated user-created specialist used to render
4143
- twice, the second time as Shipped. The account plugin tree is the authorship
4144
- evidence and its row wins; it is the same discriminator `disable` requires.
4145
- Both gates read filenames off disk, so a plugin file whose frontmatter does not
4146
- parse still suppresses its live twin it is authored either way, and
4147
- `specialistsSkipped` is what reports the parse failure. **The exclusion covers
4148
- both account directories, live and quarantine.** It was live-only while only a
4149
- shipped agent could be quarantined; now that an authored specialist can be
4150
- switched off, its specialist row carries the plugin, the skills, the detail
4151
- route and its own disabled state, so a second row from the shipped walk would
4152
- be a duplicate with none of that. The bundled templates are never deduped: a
4153
- bundled name is shipped by definition. Each exclusion logs
4154
- `op=list-shipped-dedup file=<name>` and the count rides `op=list` and the
4155
- response as `deduped`.
4193
+ **A file in the LIVE or QUARANTINE directory whose name also exists under
4194
+ `<accountDir>/plugins/*/agents/` is excluded from this set only when the two
4195
+ files agree.** `agent-builder` copies the authored file into
4196
+ `specialists/agents/` because presence there is what makes an agent
4197
+ dispatchable, so the live directory says nothing about who wrote the agent and
4198
+ every activated user-created specialist used to render twice, the second time
4199
+ as Shipped. But the filename alone was also not evidence that the live file IS
4200
+ that copy: `computeSpecialistDomains` builds the spawn manifest from the live
4201
+ file, so an excluded row could describe an agent nobody would run, and a
4202
+ premium agent which reaches an account only through the live directory, since
4203
+ the bundled templates carry no `--` name lost its only row to an authored
4204
+ file of the same name, its risk class replaced by that file's. **The test is
4205
+ the three fields the card shows and the prompt reads: `name`, `description`,
4206
+ and `tools` compared as a set.** Agreement means one row, exactly as before.
4207
+ Disagreement means both rows render and `op=list-shipped-divergent` names both
4208
+ files and the differing fields. Tools compare as a set rather than as the raw
4209
+ line, because a reordered `tools:` declares the same surface and derives the
4210
+ same class. The body is never compared: the card does not render the system
4211
+ prompt, so a body-only edit does not make the row wrong. A read failure on
4212
+ either side also keeps the row, because an unreadable file cannot be proven
4213
+ equal to anything and keeping it hides nothing — but it is reported as a
4214
+ compare failure, not as a divergence, since nothing was read to disagree. An
4215
+ authored file that does not parse therefore no longer suppresses its live
4216
+ twin. **That test answers a different
4217
+ question to the write gates.** `disable` and `enable` still key on the filename
4218
+ alone, because authorship is a property of the tree a file sits in, not of its
4219
+ frontmatter, so the operator keeps the control on an agent of their own whose
4220
+ frontmatter is broken. **The comparison covers both account directories, live
4221
+ and quarantine.** It was live-only while only a shipped agent could be
4222
+ quarantined; now that an authored specialist can be switched off, its
4223
+ specialist row carries the plugin, the skills, the detail route and its own
4224
+ disabled state, so a second row from the shipped walk would be a duplicate with
4225
+ none of that. The bundled templates are never compared: a bundled name is
4226
+ shipped by definition and has no authored twin to be a copy of. Each exclusion
4227
+ logs `op=list-shipped-dedup file=<name>`; each kept pair logs
4228
+ `op=list-shipped-divergent`. Both counts ride `op=list` and the response, as
4229
+ `deduped` and `divergent`.
4156
4230
 
4157
4231
  The former "Public" flyout toggle in the account menu was removed; this page is
4158
4232
  the sole agent surface.
@@ -4322,7 +4396,7 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
4322
4396
 
4323
4397
  | Route | Behaviour |
4324
4398
  |-------|-----------|
4325
- | `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. |
4399
+ | `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. |
4326
4400
  | `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. |
4327
4401
  | `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. |
4328
4402
  | `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 +4442,13 @@ on** (`accountId=<id8>`) — a well-formed answer about the wrong account is
4368
4442
  otherwise indistinguishable from a correct one, which is exactly how an empty
4369
4443
  Agents page survived undiagnosed on a multi-account install.
4370
4444
 
4371
- - `op=list accountId=<id8> agents=<n> specialists=<m> skipped=<x> specialistsSkipped=<y>`
4372
- the heartbeat. Compare `accountId` against the account the operator is
4373
- viewing; `skipped>0`/`specialistsSkipped>0` is a malformed-source signal the
4374
- page renders as a banner, and `specialists=0` with user plugins present is the
4375
- broken-walk signature.
4445
+ - `op=list accountId=<id8> agents=<n> specialists=<m> shipped=<s> skipped=<x>
4446
+ specialistsSkipped=<y> shippedSkipped=<z> deduped=<d> divergent=<v>` the
4447
+ heartbeat. Compare `accountId` against the account the operator is viewing;
4448
+ `skipped>0`/`specialistsSkipped>0`/`shippedSkipped>0` is a malformed-source
4449
+ signal the page renders as a banner, and `specialists=0` with user plugins
4450
+ present is the broken-walk signature. `deduped` and `divergent` are described
4451
+ under their own lines below.
4376
4452
  - `op=detail accountId=<id8> slug=<…> kind=<public|specialist>` — with
4377
4453
  `present=<comma-list|none>` on the public branch, where a role absent for an
4378
4454
  agent expected complete is the missing-doc signature. One
@@ -4399,13 +4475,32 @@ Agents page survived undiagnosed on a multi-account install.
4399
4475
  - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
4400
4476
  `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
4401
4477
  graph-cleanup throw).
4402
- - `op=list-shipped-dedup file=<name>` — one line per live-directory candidate
4403
- dropped as an authored duplicate, with `deduped=<n>` on the `op=list` line and
4404
- in the response. `shipped + shippedSkipped + deduped` equals the number of
4405
- distinct `.md` names across the three source directories, so a listing that
4406
- does not add up is visible without reproducing anything. The over-exclusion to
4407
- watch for is a `deduped` line naming a file that is also a bundled or premium
4408
- agent: the authored file then hides a genuinely shipped one.
4478
+ - `op=list-shipped-dedup file=<name>` — one line per live-directory or
4479
+ quarantine-directory candidate dropped as an authored duplicate, with
4480
+ `deduped=<n>` on the `op=list` line and in the response. `shipped +
4481
+ shippedSkipped + deduped` equals the number of distinct `.md` names across the
4482
+ three source directories, so a listing that does not add up is visible without
4483
+ reproducing anything. The over-exclusion to watch for is a `deduped` line
4484
+ naming a file that is also a bundled or premium agent: the authored file then
4485
+ hides a genuinely shipped one, which now requires it to have reproduced that
4486
+ agent's `name`, `description` and `tools` exactly.
4487
+ - `op=list-shipped-divergent file=<name> found=<path> authored=<path>
4488
+ fields=<comma-list>` — one line per candidate KEPT because it does not match
4489
+ the authored copy, naming both files and which of `name`, `description`,
4490
+ `tools` differ. Without it a divergence emits nothing: both files parse and the
4491
+ row renders green, so "the row is stale" is indistinguishable from "the agent
4492
+ changed" without diffing the account tree by hand. `found=` rather than
4493
+ `live=`, because the candidate may have come from the quarantine directory and
4494
+ the path itself says which. `divergent=<n>` rides the `op=list` line and the
4495
+ response. A kept candidate is parsed like any other, so it lands in `shipped`,
4496
+ or in `shippedSkipped` when its own frontmatter carries no `name:` — either
4497
+ way `divergent` is never a fourth term and the identity above is unchanged.
4498
+ - `op=list-shipped-compare-failed file=<name> side=<found|authored>
4499
+ reason="<msg>"` — a frontmatter read threw during that comparison. The row is
4500
+ kept, because an unreadable file proves nothing, but it is **not** counted in
4501
+ `divergent`: "could not read one of them" and "the two disagree" are different
4502
+ facts, and reporting the first as the second would put drift in the count that
4503
+ nobody observed.
4409
4504
  - `[agents] op=risk account=<id8> slug=<name> origin=<shipped|public|specialist>
4410
4505
  class=<green|amber|red> rule=<id|none> riskiestTool=<tool> tools=<n>
4411
4506
  unresolved=<n> unresolvedTools=<comma-list|none> disabled=<bool>` — one line
@@ -6106,6 +6201,12 @@ The `brand-excluded` branch closes the recurring crash-restart loop on brands th
6106
6201
 
6107
6202
  **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`.
6108
6203
 
6204
+ **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`.
6205
+
6206
+ 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.
6207
+
6208
+ 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`.
6209
+
6109
6210
  **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.
6110
6211
 
6111
6212
  **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 +6766,16 @@ Note: passing an explicit second argument (e.g. `logs-read.sh <key> agent-stream
6665
6766
 
6666
6767
  **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.
6667
6768
 
6769
+ ## Stylesheet text is visible on a client document, or a styled box has lost its rules
6770
+
6771
+ **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.
6772
+
6773
+ **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.
6774
+
6775
+ **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.
6776
+
6777
+ **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.
6778
+
6668
6779
  ## First user-domain write rejected by `[graph-write-gate] reject reason=no-admin-user`
6669
6780
 
6670
6781
  **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.
@@ -9,6 +9,14 @@ Invoked by the admin agent directly.
9
9
 
10
10
  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.
11
11
 
12
+ ## 2026-08-07 (0.1.574)
13
+
14
+ - 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.
15
+ - 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.
16
+ - 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.
17
+ - An account whose specialists are present but never actually used is now detected and reported, rather than looking healthy indefinitely.
18
+ - 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.
19
+
12
20
  ## 2026-08-07 (0.1.573)
13
21
 
14
22
  - 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.
@@ -436,24 +436,43 @@ both `kind: 'specialist'` and differ only by origin.
436
436
  repair, and it is not what runs unattended: an agent runs only when something
437
437
  dispatches it, an inbound message is operator-initiated, so the only autonomous
438
438
  path is the scheduler. The modal says so and points at the routines instead.
439
- **A file in the LIVE directory whose name also exists under
440
- `<accountDir>/plugins/*/agents/` is excluded from this set.** `agent-builder`
441
- copies the authored file into `specialists/agents/` because presence there is
442
- what makes an agent dispatchable, so the live directory says nothing about who
443
- wrote the agent and every activated user-created specialist used to render
444
- twice, the second time as Shipped. The account plugin tree is the authorship
445
- evidence and its row wins; it is the same discriminator `disable` requires.
446
- Both gates read filenames off disk, so a plugin file whose frontmatter does not
447
- parse still suppresses its live twin it is authored either way, and
448
- `specialistsSkipped` is what reports the parse failure. **The exclusion covers
449
- both account directories, live and quarantine.** It was live-only while only a
450
- shipped agent could be quarantined; now that an authored specialist can be
451
- switched off, its specialist row carries the plugin, the skills, the detail
452
- route and its own disabled state, so a second row from the shipped walk would
453
- be a duplicate with none of that. The bundled templates are never deduped: a
454
- bundled name is shipped by definition. Each exclusion logs
455
- `op=list-shipped-dedup file=<name>` and the count rides `op=list` and the
456
- response as `deduped`.
439
+ **A file in the LIVE or QUARANTINE directory whose name also exists under
440
+ `<accountDir>/plugins/*/agents/` is excluded from this set only when the two
441
+ files agree.** `agent-builder` copies the authored file into
442
+ `specialists/agents/` because presence there is what makes an agent
443
+ dispatchable, so the live directory says nothing about who wrote the agent and
444
+ every activated user-created specialist used to render twice, the second time
445
+ as Shipped. But the filename alone was also not evidence that the live file IS
446
+ that copy: `computeSpecialistDomains` builds the spawn manifest from the live
447
+ file, so an excluded row could describe an agent nobody would run, and a
448
+ premium agent which reaches an account only through the live directory, since
449
+ the bundled templates carry no `--` name lost its only row to an authored
450
+ file of the same name, its risk class replaced by that file's. **The test is
451
+ the three fields the card shows and the prompt reads: `name`, `description`,
452
+ and `tools` compared as a set.** Agreement means one row, exactly as before.
453
+ Disagreement means both rows render and `op=list-shipped-divergent` names both
454
+ files and the differing fields. Tools compare as a set rather than as the raw
455
+ line, because a reordered `tools:` declares the same surface and derives the
456
+ same class. The body is never compared: the card does not render the system
457
+ prompt, so a body-only edit does not make the row wrong. A read failure on
458
+ either side also keeps the row, because an unreadable file cannot be proven
459
+ equal to anything and keeping it hides nothing — but it is reported as a
460
+ compare failure, not as a divergence, since nothing was read to disagree. An
461
+ authored file that does not parse therefore no longer suppresses its live
462
+ twin. **That test answers a different
463
+ question to the write gates.** `disable` and `enable` still key on the filename
464
+ alone, because authorship is a property of the tree a file sits in, not of its
465
+ frontmatter, so the operator keeps the control on an agent of their own whose
466
+ frontmatter is broken. **The comparison covers both account directories, live
467
+ and quarantine.** It was live-only while only a shipped agent could be
468
+ quarantined; now that an authored specialist can be switched off, its
469
+ specialist row carries the plugin, the skills, the detail route and its own
470
+ disabled state, so a second row from the shipped walk would be a duplicate with
471
+ none of that. The bundled templates are never compared: a bundled name is
472
+ shipped by definition and has no authored twin to be a copy of. Each exclusion
473
+ logs `op=list-shipped-dedup file=<name>`; each kept pair logs
474
+ `op=list-shipped-divergent`. Both counts ride `op=list` and the response, as
475
+ `deduped` and `divergent`.
457
476
 
458
477
  The former "Public" flyout toggle in the account menu was removed; this page is
459
478
  the sole agent surface.
@@ -623,7 +642,7 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
623
642
 
624
643
  | Route | Behaviour |
625
644
  |-------|-----------|
626
- | `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. |
645
+ | `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. |
627
646
  | `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. |
628
647
  | `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. |
629
648
  | `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. |
@@ -669,11 +688,13 @@ on** (`accountId=<id8>`) — a well-formed answer about the wrong account is
669
688
  otherwise indistinguishable from a correct one, which is exactly how an empty
670
689
  Agents page survived undiagnosed on a multi-account install.
671
690
 
672
- - `op=list accountId=<id8> agents=<n> specialists=<m> skipped=<x> specialistsSkipped=<y>`
673
- the heartbeat. Compare `accountId` against the account the operator is
674
- viewing; `skipped>0`/`specialistsSkipped>0` is a malformed-source signal the
675
- page renders as a banner, and `specialists=0` with user plugins present is the
676
- broken-walk signature.
691
+ - `op=list accountId=<id8> agents=<n> specialists=<m> shipped=<s> skipped=<x>
692
+ specialistsSkipped=<y> shippedSkipped=<z> deduped=<d> divergent=<v>` the
693
+ heartbeat. Compare `accountId` against the account the operator is viewing;
694
+ `skipped>0`/`specialistsSkipped>0`/`shippedSkipped>0` is a malformed-source
695
+ signal the page renders as a banner, and `specialists=0` with user plugins
696
+ present is the broken-walk signature. `deduped` and `divergent` are described
697
+ under their own lines below.
677
698
  - `op=detail accountId=<id8> slug=<…> kind=<public|specialist>` — with
678
699
  `present=<comma-list|none>` on the public branch, where a role absent for an
679
700
  agent expected complete is the missing-doc signature. One
@@ -700,13 +721,32 @@ Agents page survived undiagnosed on a multi-account install.
700
721
  - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
701
722
  `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
702
723
  graph-cleanup throw).
703
- - `op=list-shipped-dedup file=<name>` — one line per live-directory candidate
704
- dropped as an authored duplicate, with `deduped=<n>` on the `op=list` line and
705
- in the response. `shipped + shippedSkipped + deduped` equals the number of
706
- distinct `.md` names across the three source directories, so a listing that
707
- does not add up is visible without reproducing anything. The over-exclusion to
708
- watch for is a `deduped` line naming a file that is also a bundled or premium
709
- agent: the authored file then hides a genuinely shipped one.
724
+ - `op=list-shipped-dedup file=<name>` — one line per live-directory or
725
+ quarantine-directory candidate dropped as an authored duplicate, with
726
+ `deduped=<n>` on the `op=list` line and in the response. `shipped +
727
+ shippedSkipped + deduped` equals the number of distinct `.md` names across the
728
+ three source directories, so a listing that does not add up is visible without
729
+ reproducing anything. The over-exclusion to watch for is a `deduped` line
730
+ naming a file that is also a bundled or premium agent: the authored file then
731
+ hides a genuinely shipped one, which now requires it to have reproduced that
732
+ agent's `name`, `description` and `tools` exactly.
733
+ - `op=list-shipped-divergent file=<name> found=<path> authored=<path>
734
+ fields=<comma-list>` — one line per candidate KEPT because it does not match
735
+ the authored copy, naming both files and which of `name`, `description`,
736
+ `tools` differ. Without it a divergence emits nothing: both files parse and the
737
+ row renders green, so "the row is stale" is indistinguishable from "the agent
738
+ changed" without diffing the account tree by hand. `found=` rather than
739
+ `live=`, because the candidate may have come from the quarantine directory and
740
+ the path itself says which. `divergent=<n>` rides the `op=list` line and the
741
+ response. A kept candidate is parsed like any other, so it lands in `shipped`,
742
+ or in `shippedSkipped` when its own frontmatter carries no `name:` — either
743
+ way `divergent` is never a fourth term and the identity above is unchanged.
744
+ - `op=list-shipped-compare-failed file=<name> side=<found|authored>
745
+ reason="<msg>"` — a frontmatter read threw during that comparison. The row is
746
+ kept, because an unreadable file proves nothing, but it is **not** counted in
747
+ `divergent`: "could not read one of them" and "the two disagree" are different
748
+ facts, and reporting the first as the second would put drift in the count that
749
+ nobody observed.
710
750
  - `[agents] op=risk account=<id8> slug=<name> origin=<shipped|public|specialist>
711
751
  class=<green|amber|red> rule=<id|none> riskiestTool=<tool> tools=<n>
712
752
  unresolved=<n> unresolvedTools=<comma-list|none> disabled=<bool>` — one line
@@ -96,19 +96,11 @@ defect. Turns that answered no inbound — subagent side-chains, turns driven fr
96
96
  claude.ai — are deliberately outside that set: the credit guards are what keep
97
97
  them out of a customer's chat.
98
98
 
99
- Each door's `src/parity.test.ts` asserts the contract end to end against a real
100
- JSONL and the real follower.
101
-
102
- **Six discard sites, each now logged.** A follower outcome is dropped at:
103
-
104
- | File | Guard | `reason=` |
105
- |---|---|---|
106
- | `telegram-channel/src/server.ts:241` | `pendingTurns <= 0` | `no-credit` |
107
- | `webchat-channel/src/server.ts:378` | `pendingTurns <= 0` | `no-credit` |
108
- | `whatsapp-channel/src/server.ts:481` | `pendingTurns <= 0` | `no-credit` |
109
- | `whatsapp-channel/src/server.ts:489` | `consumedInbounds <= 0` | `no-consumed-inbound` |
110
- | `whatsapp-channel/src/server.ts:617` | `pendingTurns <= 0` (2nd follower) | `no-credit` |
111
- | `whatsapp-channel/src/server.ts:620` | `consumedInbounds <= 0` (2nd follower) | `no-consumed-inbound` |
99
+ **Discard sites.** The WhatsApp and Telegram followers and their credit ledgers
100
+ were removed, so those two doors now have none: one emitter reads the JSONL and
101
+ the fan-out decides where an answer goes. Only webchat still carries credit
102
+ guards, in `webchat-channel/src/server.ts`, and `src/parity.test.ts` survives
103
+ for that door alone.
112
104
 
113
105
  ```
114
106
  [channel-fanout] op=fan-out reached=… notReached=… segments=… messageId=… sessionId=…
@@ -119,6 +111,39 @@ JSONL and the real follower.
119
111
  census prints every cycle, including when the counts agree: an absent line means
120
112
  the census stopped, never that delivery is healthy.
121
113
 
114
+ ## What a second door actually requires
115
+
116
+ Reaching a door other than the one the message arrived on needs two facts.
117
+
118
+ **The person must be resolvable from the turn's sender.** That resolution reads
119
+ one place: the admin's `users.json` entry. `phone` (E.164) identifies a WhatsApp
120
+ sender; `telegram` (the chat id, matched exactly) identifies a Telegram sender.
121
+ `account.json` `whatsapp.adminPhones` is a different store with a different job:
122
+ it says a number may reach the admin agent, not whose number it is, which is why
123
+ adding a phone there binds nobody. Set the bindings with `admin-bind`, or at
124
+ creation with `admin-add`'s `phone` and `telegram`.
125
+
126
+ **The other door must hold a live target for that person.** `phone` addresses
127
+ WhatsApp when a Telegram turn wants to reach it, and `telegram` addresses
128
+ Telegram from a WhatsApp turn. Two-way reach needs both fields, not one.
129
+
130
+ The three lines that name each failure:
131
+
132
+ | Line | Means |
133
+ |---|---|
134
+ | `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | no binding, so no second door is even looked for |
135
+ | `[channel-fanout] op=no-target origin=… reason=no-admin-user` | the same fact, observed at the fan-out |
136
+ | `[channel-fanout] op=no-target origin=… reason=origin-not-live` | the door holds no live target for this key |
137
+
138
+ A Telegram bot owned by a `role:'client'` sub-account can never resolve an
139
+ admin: both resolvers return null on a client account before reading any chat
140
+ id. No binding fixes that; the bot has to live on the house account.
141
+
142
+ `[whatsapp-account-scope] op=non-uuid-account caller=fan-out` means the fan-out
143
+ was handed a Baileys credential dirname where a platform UUID belongs. That is
144
+ the defect that stranded a live admin answer, and the line exists so the next
145
+ occurrence announces itself instead of being inferred from a silent miss.
146
+
122
147
  **Read them in `server.log`.** Both are emitted by the ui-server, which now owns
123
148
  the one emitter between the session JSONL and every channel. The per-door
124
149
  `op=turn-drop` and `op=census` lines that used to sit in