@rubytech/create-realagent-code 0.1.593 → 0.1.594

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.593",
+  "version": "0.1.594",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"
@@ -13,7 +13,7 @@
     "build": "tsc",
     "bundle": "node scripts/bundle.js",
     "test": "npm run build && node --test 'dist/__tests__/*.test.js'",
-    "prepublishOnly": "bash ../../platform/scripts/verify-skill-tool-surface.sh && node ../../platform/scripts/check-plugin-tools-mcp-consistency.mjs && node ../../platform/scripts/check-risk-class.mjs && node ../../platform/scripts/check-specialist-tool-surface.mjs && node ../../platform/scripts/check-agent-contract.mjs && node ../../platform/scripts/check-routing-prose-bash.mjs && node ../../platform/scripts/check-no-task-id-leaks.mjs && node ../../platform/scripts/check-no-esm-require.mjs && node ../../platform/scripts/check-no-raw-mcp-registrations.mjs && node ../../platform/scripts/check-skill-load-coverage.mjs && node ../../platform/scripts/check-routine-roster-doc.mjs && node ../../platform/scripts/check-architecture-skill-no-drift.mjs && node ../../platform/ui/scripts/check-brand-fonts.mjs && node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && node --test 'dist/__tests__/*.test.js' && chmod +x dist/index.js && npm run bundle && bash ../../platform/scripts/smoke-boot-services.sh && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
+    "prepublishOnly": "bash ../../platform/scripts/verify-skill-tool-surface.sh && node ../../platform/scripts/check-plugin-tools-mcp-consistency.mjs && node ../../platform/scripts/check-risk-class.mjs && node ../../platform/scripts/check-specialist-tool-surface.mjs && node ../../platform/scripts/check-agent-contract.mjs && node ../../platform/scripts/check-routing-prose-bash.mjs && node ../../platform/scripts/check-no-task-id-leaks.mjs && node ../../platform/scripts/check-no-esm-require.mjs && node ../../platform/scripts/check-no-raw-mcp-registrations.mjs && node ../../platform/scripts/check-skill-load-coverage.mjs && node ../../platform/scripts/check-routine-roster-doc.mjs && node ../../platform/scripts/check-architecture-skill-no-drift.mjs && node ../../platform/ui/scripts/check-brand-fonts.mjs && node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && node --test 'dist/__tests__/*.test.js' && chmod +x dist/index.js && node ../../platform/scripts/check-orphan-dist.mjs && npm run bundle && bash ../../platform/scripts/smoke-boot-services.sh && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
   },
   "files": [
     "dist",

package/payload/platform/package.json

@@ -12,6 +12,7 @@
   "scripts": {
     "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
     "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/tsconfig.json",
+    "clean:dist": "node scripts/check-orphan-dist.mjs --remove",
     "gen:canonical-tools": "node scripts/generate-canonical-tool-names.mjs",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",

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

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Real Agent ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:c66d6d534933072b64b3b80ac132135ee30f82b6eb50a4a7950a6500cf0ca678
+content-hash: sha256:ea35aa77226e01aad93c7b90e9118e4e993a58cb980330b28541dcbb3122a993
 brand: realagent-code
 product-name: Real Agent
 ---
@@ -2866,7 +2866,9 @@ Real Agent asks for your bot token, then asks what kind of bot this is:
 
 - an **admin bot** — only your numeric Telegram IDs may message it, and it answers as your admin agent;
 - a **public bot** — customer-facing, with a DM policy, answering as one of your account's agents;
-- a **specialist bot** — bound to one of your own specialists, so messaging it runs that specialist with its own instructions and its own tools rather than your admin agent. You name the specialist and the numeric IDs allowed to reach it. Both are required: there is no open setting for this kind, because the specialist has real tools rather than the reply-only surface a public bot gets.
+- a **specialist bot** — bound to one of your own specialists, so messaging it runs that specialist with its own instructions and its own tools rather than your admin agent. You name the specialist and the numeric IDs allowed to reach it. Both are required: there is no open setting for this kind, because a specialist carries whatever tools its card gives it, while a public bot is held to a fixed set nobody can widen.
+
+A public Telegram bot holds five things and nothing else: the reply that carries its answer, cards with tappable buttons, polls and quizzes and map pins, outgoing photos and documents and voice notes, and the ability to open a file a visitor sent it. That set is fixed by the platform for every public agent on every account, so there is no tools setting on an agent to turn any of it on or off. A public bot on webchat or WhatsApp still has the reply alone, because those channels ship no equivalent set.
 
 It verifies the token, registers the bot's webhook on your brand's edge, stores the token under your brand's config (never in a shared system directory), and sets whichever agent or specialist will answer. The bot is now connected.
 
@@ -6455,7 +6457,7 @@ For subagents, the same spawn pushes `--add-dir` for every bundled plugin agents
 
 A boot gate refuses to start the manager when any admin-allowlisted tool `mcp__<plugin>__*` lacks a registered server. The signal is `boot-failed reason=mcp-allowlist-without-server plugin=<p> tool=<t>` followed by `process.exit(1)`. The remediation is a one-line edit to the named `PLUGIN.md`: add the `mcp:` block. The complementary observability emit `mcp-config-allowlist-coverage admin-tools=A admin-registered=R` (where `A === R`) confirms the invariant per boot.
 
-**Whether a plugin's server mounts is decided by the generated manifest, not the `mcp:` block.** A plugin ships its MCP as `mcp/`; the manifest generator ([`scripts/generate-plugin-manifests.mjs`](../../../../scripts/generate-plugin-manifests.mjs), run at bundle time over the payload) reads the plugin's `mcp-manifest:` frontmatter. `auto` emits an `mcpServers` block into the generated `.claude-plugin/plugin.json` — routed through `lib/mcp-spawn-tee`, carrying no per-session env (`LOG_DIR`/`SESSION_ID`/`ACCOUNT_ID`/`NEO4J_*`/`PLATFORM_ROOT` ride the PTY env block described above) — and copies the tee into the plugin's `lib/`; `skip` emits nothing, so Claude Code never spawns the server. The generator recognises two server shapes. A plugin-local `mcp/` (its `hasMcp` check: `mcp/dist/index.js` or `mcp/package.json`) uses `auto` or `skip`. A tool-plugin whose `mcp:` server is a shared `platform/lib/<name>` binary rather than a plugin-local `mcp/` (e.g. `graph`, served by `platform/lib/graph-mcp`) is annotated `mcp-manifest: shared-lib`: the generator emits that plugin's `mcp:` block verbatim into `mcpServers` — command, args (anchored on `${PLATFORM_ROOT}`, routed through the shared `lib/mcp-spawn-tee`), and env — which Claude Code expands at spawn from the PTY env block. No tee copy is made into the plugin, because both the tee and the server resolve from `${PLATFORM_ROOT}` outside the per-plugin cache. `graph` is the one shared-lib tool-plugin; every other tool-plugin ships a plugin-local `mcp/` and uses `auto`. A plugin with an `mcp:` block, no plugin-local `mcp/`, and no `mcp-manifest: shared-lib` annotation is a FATAL at generation time. Premium plugins import platform libs (`mcp-lifeline`, etc.) via a source-tree relative path; the bundler's premium-lib shipper (`packages/create-maxy-code/scripts/bundle.js`) rewrites that path and vendors each referenced `platform/lib/<name>` into `premium-plugins/<bundle>/lib/<name>/`, so the auto-mounted dist resolves its imports. The `mcp-allowlist-without-server` gate above proves only that a plugin's PLUGIN.md `mcp:` block matches its allowlist — it reads source, not the generated manifest — so a plugin left on `skip` passes that gate while its server silently never mounts (its tools are listed but not live). The `tool-registration` gate below closes that blind spot.
+**Whether a plugin's server mounts is decided by the generated manifest, not the `mcp:` block.** A plugin ships its MCP as `mcp/`; the manifest generator ([`scripts/generate-plugin-manifests.mjs`](../../../../scripts/generate-plugin-manifests.mjs), run at bundle time over the payload) reads the plugin's `mcp-manifest:` frontmatter. `auto` emits an `mcpServers` block into the generated `.claude-plugin/plugin.json` — routed through `lib/mcp-spawn-tee`, carrying no per-session env (`LOG_DIR`/`SESSION_ID`/`ACCOUNT_ID`/`NEO4J_*`/`PLATFORM_ROOT` ride the PTY env block described above) — and copies the tee into the plugin's `lib/`; `skip` emits nothing, so Claude Code never spawns the server. `skip` covers two shapes: a plugin whose canonical surface is a user-scoped MCP, and a plugin that registers zero tools and keeps `mcp/` only as a test host — `cloudflare` is the latter, so its `skip` is not a pointer to a server elsewhere. The generator recognises two server shapes. A plugin-local `mcp/` (its `hasMcp` check: `mcp/dist/index.js` or `mcp/package.json`) uses `auto` or `skip`. A tool-plugin whose `mcp:` server is a shared `platform/lib/<name>` binary rather than a plugin-local `mcp/` (e.g. `graph`, served by `platform/lib/graph-mcp`) is annotated `mcp-manifest: shared-lib`: the generator emits that plugin's `mcp:` block verbatim into `mcpServers` — command, args (anchored on `${PLATFORM_ROOT}`, routed through the shared `lib/mcp-spawn-tee`), and env — which Claude Code expands at spawn from the PTY env block. No tee copy is made into the plugin, because both the tee and the server resolve from `${PLATFORM_ROOT}` outside the per-plugin cache. `graph` is the one shared-lib tool-plugin; every other tool-plugin ships a plugin-local `mcp/` and uses `auto`. A plugin with an `mcp:` block, no plugin-local `mcp/`, and no `mcp-manifest: shared-lib` annotation is a FATAL at generation time. Premium plugins import platform libs (`mcp-lifeline`, etc.) via a source-tree relative path; the bundler's premium-lib shipper (`packages/create-maxy-code/scripts/bundle.js`) rewrites that path and vendors each referenced `platform/lib/<name>` into `premium-plugins/<bundle>/lib/<name>/`, so the auto-mounted dist resolves its imports. The `mcp-allowlist-without-server` gate above proves only that a plugin's PLUGIN.md `mcp:` block matches its allowlist — it reads source, not the generated manifest — so a plugin left on `skip` passes that gate while its server silently never mounts (its tools are listed but not live). The `tool-registration` gate below closes that blind spot.
 
 A second boot gate walks every specialist `.md` under `platform/templates/specialists/agents/`, every bundled `<plugin>/agents/` directory, and the per-account `<accountDir>/specialists/agents/` directory, parses each file's `tools:` frontmatter line (canonical long-prefix names), and classifies every tool name as one of: CC-native (Read, Bash, …), a tool the loaded `PLUGIN.md` set actually serves (matched as the long canonical name in `toolSurface.all`), a third-party MCP bridge (a `mcp__plugin_*` name whose plugin segment is NOT a maxy platform plugin — Playwright etc., upstream-owned, passes unconditionally), `unknown-tool-in-plugin` (maxy plugin namespace served but tool name absent), `unknown-plugin-namespace` (namespace served by nothing), `brand-excluded-plugin` (namespace served by nothing on this brand, **but** the brand's `brand.json#plugins.excluded` list names it), or `malformed-name` (not CC-native and not `mcp__`-shaped). The first three pass. The next two refuse boot with one `boot-failed reason=specialist-tool-drift specialist=<name> tool=<t> drift=<class> path=<…>` line per defect, then `process.exit(1)`. A maxy-plugin `mcp__plugin_*` name is validated against `toolSurface.all`, so a typo or stale long-prefix tool name still refuses boot rather than passing as a bridge; the build-time `check-canonical-tool-names.mjs` gate catches the same drift in instruction files before publish. `brand-excluded-plugin` is a structural pass: it lands in a per-specialist strip-list, the manager continues to boot, and at spawn time `pty-spawner` removes those tool names from the `--agent <name>` spawn's `--allowed-tools` argv. The complementary observability emit `specialist-tool-strip specialist=<name> plugin=<p> tools=<csv> reason=brand-excluded` fires one line per stripped (specialist, plugin) pair so an operator who reads `server.log` sees the brand filter doing work without cross-referencing `brand.json` against the template. The startup-self-test line `startup-self-test specialist-tool-drift=ok inspected=<N> stripped-specialists=<M>` confirms the gate ran and how many specialists carry strip-lists.
 

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

@@ -9,6 +9,11 @@ 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-11 (0.1.594)
+
+- A public Telegram bot no longer tells people it cannot do things it can. Its own description denied the tools it had actually been given, so it refused work it was equipped for.
+- Code deleted from the platform no longer ships anyway. Removing a source file left its compiled output behind, so retired code was still being packaged and installed.
+
 ## 2026-08-11 (0.1.593)
 
 - A public Telegram bot can now use buttons, media and the rest of the channel. It held no tool at all, so every answer it gave was plain text.

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -28,6 +28,8 @@ Each installation has its own Cloudflare account. Two auth paths serve two opera
 
 The plugin registers no agent-facing MCP tools. Every Cloudflare operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, or calling the Cloudflare API with a reused per-scope narrow token, with stdout/stderr streamed verbatim into the PTY chat (secrets redacted). The OAuth URL printed by `cloudflared tunnel login` is linkified by the native PTY; the operator clicks it in their own browser. The one shell helper is [bin/cf-token.sh](bin/cf-token.sh), a deterministic per-scope token resolver that faithfully relays the Cloudflare token API (it invents no flags and drives no dashboard); there is no wrapper around `cloudflared` or `wrangler`, no orchestrator state machine, no MCP-tool surface.
 
+The frontmatter carries `mcp-manifest: skip` because the manifest generator requires an annotation from any plugin with an `mcp/` directory, and `skip` is the value that emits no `mcpServers` block. It does not mean the tools live in a user-scoped server somewhere else: there are none. `mcp/` survives only as the test host for `bin/` and for the skill templates' Pages Functions; its entry point registers nothing.
+
 ### Skills
 
 | Skill | Purpose |

package/payload/platform/plugins/docs/references/internals.md

@@ -501,7 +501,7 @@ For subagents, the same spawn pushes `--add-dir` for every bundled plugin agents
 
 A boot gate refuses to start the manager when any admin-allowlisted tool `mcp__<plugin>__*` lacks a registered server. The signal is `boot-failed reason=mcp-allowlist-without-server plugin=<p> tool=<t>` followed by `process.exit(1)`. The remediation is a one-line edit to the named `PLUGIN.md`: add the `mcp:` block. The complementary observability emit `mcp-config-allowlist-coverage admin-tools=A admin-registered=R` (where `A === R`) confirms the invariant per boot.
 
-**Whether a plugin's server mounts is decided by the generated manifest, not the `mcp:` block.** A plugin ships its MCP as `mcp/`; the manifest generator ([`scripts/generate-plugin-manifests.mjs`](../../../../scripts/generate-plugin-manifests.mjs), run at bundle time over the payload) reads the plugin's `mcp-manifest:` frontmatter. `auto` emits an `mcpServers` block into the generated `.claude-plugin/plugin.json` — routed through `lib/mcp-spawn-tee`, carrying no per-session env (`LOG_DIR`/`SESSION_ID`/`ACCOUNT_ID`/`NEO4J_*`/`PLATFORM_ROOT` ride the PTY env block described above) — and copies the tee into the plugin's `lib/`; `skip` emits nothing, so Claude Code never spawns the server. The generator recognises two server shapes. A plugin-local `mcp/` (its `hasMcp` check: `mcp/dist/index.js` or `mcp/package.json`) uses `auto` or `skip`. A tool-plugin whose `mcp:` server is a shared `platform/lib/<name>` binary rather than a plugin-local `mcp/` (e.g. `graph`, served by `platform/lib/graph-mcp`) is annotated `mcp-manifest: shared-lib`: the generator emits that plugin's `mcp:` block verbatim into `mcpServers` — command, args (anchored on `${PLATFORM_ROOT}`, routed through the shared `lib/mcp-spawn-tee`), and env — which Claude Code expands at spawn from the PTY env block. No tee copy is made into the plugin, because both the tee and the server resolve from `${PLATFORM_ROOT}` outside the per-plugin cache. `graph` is the one shared-lib tool-plugin; every other tool-plugin ships a plugin-local `mcp/` and uses `auto`. A plugin with an `mcp:` block, no plugin-local `mcp/`, and no `mcp-manifest: shared-lib` annotation is a FATAL at generation time. Premium plugins import platform libs (`mcp-lifeline`, etc.) via a source-tree relative path; the bundler's premium-lib shipper (`packages/create-maxy-code/scripts/bundle.js`) rewrites that path and vendors each referenced `platform/lib/<name>` into `premium-plugins/<bundle>/lib/<name>/`, so the auto-mounted dist resolves its imports. The `mcp-allowlist-without-server` gate above proves only that a plugin's PLUGIN.md `mcp:` block matches its allowlist — it reads source, not the generated manifest — so a plugin left on `skip` passes that gate while its server silently never mounts (its tools are listed but not live). The `tool-registration` gate below closes that blind spot.
+**Whether a plugin's server mounts is decided by the generated manifest, not the `mcp:` block.** A plugin ships its MCP as `mcp/`; the manifest generator ([`scripts/generate-plugin-manifests.mjs`](../../../../scripts/generate-plugin-manifests.mjs), run at bundle time over the payload) reads the plugin's `mcp-manifest:` frontmatter. `auto` emits an `mcpServers` block into the generated `.claude-plugin/plugin.json` — routed through `lib/mcp-spawn-tee`, carrying no per-session env (`LOG_DIR`/`SESSION_ID`/`ACCOUNT_ID`/`NEO4J_*`/`PLATFORM_ROOT` ride the PTY env block described above) — and copies the tee into the plugin's `lib/`; `skip` emits nothing, so Claude Code never spawns the server. `skip` covers two shapes: a plugin whose canonical surface is a user-scoped MCP, and a plugin that registers zero tools and keeps `mcp/` only as a test host — `cloudflare` is the latter, so its `skip` is not a pointer to a server elsewhere. The generator recognises two server shapes. A plugin-local `mcp/` (its `hasMcp` check: `mcp/dist/index.js` or `mcp/package.json`) uses `auto` or `skip`. A tool-plugin whose `mcp:` server is a shared `platform/lib/<name>` binary rather than a plugin-local `mcp/` (e.g. `graph`, served by `platform/lib/graph-mcp`) is annotated `mcp-manifest: shared-lib`: the generator emits that plugin's `mcp:` block verbatim into `mcpServers` — command, args (anchored on `${PLATFORM_ROOT}`, routed through the shared `lib/mcp-spawn-tee`), and env — which Claude Code expands at spawn from the PTY env block. No tee copy is made into the plugin, because both the tee and the server resolve from `${PLATFORM_ROOT}` outside the per-plugin cache. `graph` is the one shared-lib tool-plugin; every other tool-plugin ships a plugin-local `mcp/` and uses `auto`. A plugin with an `mcp:` block, no plugin-local `mcp/`, and no `mcp-manifest: shared-lib` annotation is a FATAL at generation time. Premium plugins import platform libs (`mcp-lifeline`, etc.) via a source-tree relative path; the bundler's premium-lib shipper (`packages/create-maxy-code/scripts/bundle.js`) rewrites that path and vendors each referenced `platform/lib/<name>` into `premium-plugins/<bundle>/lib/<name>/`, so the auto-mounted dist resolves its imports. The `mcp-allowlist-without-server` gate above proves only that a plugin's PLUGIN.md `mcp:` block matches its allowlist — it reads source, not the generated manifest — so a plugin left on `skip` passes that gate while its server silently never mounts (its tools are listed but not live). The `tool-registration` gate below closes that blind spot.
 
 A second boot gate walks every specialist `.md` under `platform/templates/specialists/agents/`, every bundled `<plugin>/agents/` directory, and the per-account `<accountDir>/specialists/agents/` directory, parses each file's `tools:` frontmatter line (canonical long-prefix names), and classifies every tool name as one of: CC-native (Read, Bash, …), a tool the loaded `PLUGIN.md` set actually serves (matched as the long canonical name in `toolSurface.all`), a third-party MCP bridge (a `mcp__plugin_*` name whose plugin segment is NOT a maxy platform plugin — Playwright etc., upstream-owned, passes unconditionally), `unknown-tool-in-plugin` (maxy plugin namespace served but tool name absent), `unknown-plugin-namespace` (namespace served by nothing), `brand-excluded-plugin` (namespace served by nothing on this brand, **but** the brand's `brand.json#plugins.excluded` list names it), or `malformed-name` (not CC-native and not `mcp__`-shaped). The first three pass. The next two refuse boot with one `boot-failed reason=specialist-tool-drift specialist=<name> tool=<t> drift=<class> path=<…>` line per defect, then `process.exit(1)`. A maxy-plugin `mcp__plugin_*` name is validated against `toolSurface.all`, so a typo or stale long-prefix tool name still refuses boot rather than passing as a bridge; the build-time `check-canonical-tool-names.mjs` gate catches the same drift in instruction files before publish. `brand-excluded-plugin` is a structural pass: it lands in a per-specialist strip-list, the manager continues to boot, and at spawn time `pty-spawner` removes those tool names from the `--agent <name>` spawn's `--allowed-tools` argv. The complementary observability emit `specialist-tool-strip specialist=<name> plugin=<p> tools=<csv> reason=brand-excluded` fires one line per stripped (specialist, plugin) pair so an operator who reads `server.log` sees the brand filter doing work without cross-referencing `brand.json` against the template. The startup-self-test line `startup-self-test specialist-tool-drift=ok inspected=<N> stripped-specialists=<M>` confirms the gate ran and how many specialists carry strip-lists.
 

package/payload/platform/plugins/docs/references/telegram-guide.md

@@ -43,7 +43,9 @@ Tell {{productName}}: "Set up Telegram" or "Configure the Telegram bot." Setup r
 
 - an **admin bot** — only your numeric Telegram IDs may message it, and it answers as your admin agent;
 - a **public bot** — customer-facing, with a DM policy, answering as one of your account's agents;
-- a **specialist bot** — bound to one of your own specialists, so messaging it runs that specialist with its own instructions and its own tools rather than your admin agent. You name the specialist and the numeric IDs allowed to reach it. Both are required: there is no open setting for this kind, because the specialist has real tools rather than the reply-only surface a public bot gets.
+- a **specialist bot** — bound to one of your own specialists, so messaging it runs that specialist with its own instructions and its own tools rather than your admin agent. You name the specialist and the numeric IDs allowed to reach it. Both are required: there is no open setting for this kind, because a specialist carries whatever tools its card gives it, while a public bot is held to a fixed set nobody can widen.
+
+A public Telegram bot holds five things and nothing else: the reply that carries its answer, cards with tappable buttons, polls and quizzes and map pins, outgoing photos and documents and voice notes, and the ability to open a file a visitor sent it. That set is fixed by the platform for every public agent on every account, so there is no tools setting on an agent to turn any of it on or off. A public bot on webchat or WhatsApp still has the reply alone, because those channels ship no equivalent set.
 
 It verifies the token, registers the bot's webhook on your brand's edge, stores the token under your brand's config (never in a shared system directory), and sets whichever agent or specialist will answer. The bot is now connected.
 

package/payload/platform/scripts/__tests__/agent-identity-reconcile.test.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Task 2671 — reconcile_all_accounts_identities converges every account's
+# public-agent IDENTITY.md against the shipped template. The failure it exists
+# for is silent: the re-sync it replaces ran for the house account alone, so a
+# sub-account's agent kept a stale prompt indefinitely and nothing said so.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLAT_SCRIPTS="$SCRIPT_DIR/.."
+PASS=0; FAIL=0; FAILED=()
+assert_eq() { if [ "$1" = "$2" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); FAILED+=("$3: expected [$2] got [$1]"); fi; }
+
+. "$PLAT_SCRIPTS/lib/agent-identity-reconcile.sh"
+
+T=$(mktemp -d)
+TPL="$T/IDENTITY.md"
+printf '# Public Agent\n\nShipped text.\n' > "$TPL"
+export MAXY_PUBLIC_IDENTITY_TEMPLATE="$TPL"
+
+seed_account() {
+  # seed_account <accounts_dir> <account_id>
+  local root="$1/$2"
+  mkdir -p "$root/agents"
+  printf '{"accountId":"%s"}\n' "$2" > "$root/account.json"
+  echo "$root"
+}
+seed_agent() {
+  # seed_agent <account_root> <slug> <body>
+  mkdir -p "$1/agents/$2"
+  printf '%s' "$3" > "$1/agents/$2/IDENTITY.md"
+}
+
+ACCTS="$T/accounts"
+A1="$(seed_account "$ACCTS" aaaaaaaa-0000-0000-0000-000000000001)"
+A2="$(seed_account "$ACCTS" bbbbbbbb-0000-0000-0000-000000000002)"
+
+seed_agent "$A1" beagle 'STALE — you have no tools.'
+seed_agent "$A1" admin  'ADMIN identity, never touched.'
+seed_agent "$A1" passive 'PASSIVE identity, never touched.'
+# Byte-identical to the template, so `cp` rather than a command substitution:
+# `$(cat …)` strips the trailing newline and the copy would read as drift.
+mkdir -p "$A2/agents/fares" && cp "$TPL" "$A2/agents/fares/IDENTITY.md"
+# An agent dir with no IDENTITY.md: counted by nothing, created by nothing.
+mkdir -p "$A2/agents/halfmade"
+# A dir with no account.json is not an account.
+mkdir -p "$ACCTS/not-an-account/agents"
+
+OUT1="$(reconcile_all_accounts_identities "$ACCTS" 2>&1)"; RC1=$?
+
+assert_eq "$RC1" "0" "clean-run-exit-zero"
+assert_eq "$(printf '%s' "$OUT1" | grep -c 'accounts=2 agents=2 divergent=1')" "1" "summary-counts"
+assert_eq "$(cat "$A1/agents/beagle/IDENTITY.md")" "$(cat "$TPL")" "stale-rewritten"
+assert_eq "$(cat "$A1/agents/admin/IDENTITY.md")" "ADMIN identity, never touched." "admin-skipped"
+assert_eq "$(cat "$A1/agents/passive/IDENTITY.md")" "PASSIVE identity, never touched." "passive-skipped"
+assert_eq "$(printf '%s' "$OUT1" | grep -c 'agent=beagle status=updated')" "1" "stale-logged-updated"
+assert_eq "$(printf '%s' "$OUT1" | grep -c 'agent=fares status=already-current')" "1" "current-logged-current"
+assert_eq "$(printf '%s' "$OUT1" | grep -c 'agent=admin\|agent=passive\|agent=halfmade')" "0" "excluded-not-logged"
+assert_eq "$([ -e "$A2/agents/halfmade/IDENTITY.md" ] && echo yes || echo no)" "no" "never-creates"
+
+# Second run: same agent count, nothing left divergent. A zero that follows a
+# non-zero is the only zero that proves the pass runs — `divergent=0` on its own
+# is what a stopped counter prints too.
+OUT2="$(reconcile_all_accounts_identities "$ACCTS" 2>&1)"; RC2=$?
+assert_eq "$RC2" "0" "idempotent-exit-zero"
+assert_eq "$(printf '%s' "$OUT2" | grep -c 'accounts=2 agents=2 divergent=0')" "1" "idempotent-summary"
+
+# Missing template: reported per agent, counted divergent, never fatal, and the
+# agent's file is left exactly as it was rather than truncated.
+export MAXY_PUBLIC_IDENTITY_TEMPLATE="$T/absent.md"
+BEFORE="$(cat "$A1/agents/beagle/IDENTITY.md")"
+OUT3="$(reconcile_all_accounts_identities "$ACCTS" 2>&1)"; RC3=$?
+assert_eq "$RC3" "0" "no-template-not-fatal"
+assert_eq "$(printf '%s' "$OUT3" | grep -c 'status=no-template')" "2" "no-template-logged-per-agent"
+assert_eq "$(printf '%s' "$OUT3" | grep -c 'accounts=2 agents=2 divergent=2')" "1" "no-template-counted-divergent"
+assert_eq "$(cat "$A1/agents/beagle/IDENTITY.md")" "$BEFORE" "no-template-leaves-file"
+
+# An empty destination after a copy aborts the install: that state traps the
+# brand server in STARTING and was observed on a live device.
+export MAXY_PUBLIC_IDENTITY_TEMPLATE="$TPL"
+printf 'drifted again' > "$A1/agents/beagle/IDENTITY.md"
+CP_STUB="$T/bin"; mkdir -p "$CP_STUB"
+printf '#!/usr/bin/env bash\n: > "${@: -1}"\nexit 0\n' > "$CP_STUB/cp"; chmod +x "$CP_STUB/cp"
+OUT4="$(PATH="$CP_STUB:$PATH" reconcile_all_accounts_identities "$ACCTS" 2>&1)"; RC4=$?
+assert_eq "$RC4" "1" "empty-copy-is-fatal"
+assert_eq "$(printf '%s' "$OUT4" | grep -c 'status=empty-after-copy')" "1" "empty-copy-logged"
+assert_eq "$(printf '%s' "$OUT4" | grep -c 'FATAL')" "1" "empty-copy-fatal-line"
+
+# setup-account.sh runs under `set -euo pipefail`, and the reconciler is called
+# there as a bare command. A non-zero from any per-agent call therefore kills the
+# whole install, and it kills it on exactly the runs that had work to do — the
+# ones where an agent diverged. Reproduced before the fix: the summary line never
+# printed and the sourcing shell exited 1 after the first `status=updated`.
+export MAXY_PUBLIC_IDENTITY_TEMPLATE="$TPL"
+printf 'drifted under set -e' > "$A1/agents/beagle/IDENTITY.md"
+OUT5="$(bash -c '
+set -euo pipefail
+. "'"$PLAT_SCRIPTS"'/lib/agent-identity-reconcile.sh"
+reconcile_all_accounts_identities "'"$ACCTS"'"
+echo REACHED-END' 2>&1)"; RC5=$?
+assert_eq "$RC5" "0" "set-e-does-not-abort"
+assert_eq "$(printf '%s' "$OUT5" | grep -c 'REACHED-END')" "1" "set-e-reaches-end"
+assert_eq "$(printf '%s' "$OUT5" | grep -c 'accounts=2 agents=2 divergent=1')" "1" "set-e-summary-printed"
+
+rm -rf "$T"
+
+if [ "$FAIL" -gt 0 ]; then
+  printf 'FAIL %d, PASS %d\n' "$FAIL" "$PASS"
+  printf '  %s\n' "${FAILED[@]}"
+  exit 1
+fi
+printf 'PASS %d\n' "$PASS"

package/payload/platform/scripts/__tests__/check-orphan-dist.test.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# The orphan-dist gate. A compiled .js whose .ts was deleted must fail; a
+# nested path must map by its relative path, not its basename; a dist whose
+# whole project is gone must be reported as a project orphan rather than one
+# line per file; and a run that finds no dist tree at all must fail rather
+# than report a clean zero, because "measured nothing" and "found nothing"
+# are different answers.
+set -u
+GATE="$(cd "$(dirname "$0")/.." && pwd)/check-orphan-dist.mjs"
+[[ -f "$GATE" ]] || { echo "FAIL: gate script missing at $GATE" >&2; exit 1; }
+PASS=0; FAIL=0
+
+ROOT=$(mktemp -d)
+trap 'rm -rf "$ROOT"' EXIT
+
+reset_root() { rm -rf "$ROOT/platform"; mkdir -p "$ROOT/platform"; }
+
+# The plugins family nests its project under mcp/; lib and services do not.
+fam_base() { # $1=family $2=project $3=dist|src
+  if [[ "$1" == plugins ]]; then echo "$ROOT/platform/$1/$2/mcp/$3"; else echo "$ROOT/platform/$1/$2/$3"; fi
+}
+make_out() { local b; b="$(fam_base "$1" "$2" dist)"; mkdir -p "$b/$(dirname "$3")"; printf 'export {};\n' > "$b/$3"; }
+make_src() { local b; b="$(fam_base "$1" "$2" src)";  mkdir -p "$b/$(dirname "$3")"; printf 'export {};\n' > "$b/$3"; }
+
+check() { # $1=desc $2=expected-exit $3=expected substring (may be empty)
+  local desc="$1" expected="$2" needle="${3:-}" out got
+  out=$(node "$GATE" "$ROOT/platform" 2>&1); got=$?
+  if [[ "$got" -ne "$expected" ]]; then
+    echo "FAIL: $desc — expected exit $expected, got $got"; printf '%s\n' "$out" | sed 's/^/      /'
+    FAIL=$((FAIL+1)); return
+  fi
+  if [[ -n "$needle" ]] && ! printf '%s' "$out" | grep -qF -- "$needle"; then
+    echo "FAIL: $desc — output missing [$needle]"; printf '%s\n' "$out" | sed 's/^/      /'
+    FAIL=$((FAIL+1)); return
+  fi
+  echo "PASS: $desc"; PASS=$((PASS+1))
+}
+
+reset_root
+make_src plugins alpha index.ts; make_out plugins alpha index.js
+check "a compiled file with its source passes" 0 "orphans=0"
+
+reset_root
+make_src plugins alpha lib/nested.ts; make_out plugins alpha lib/nested.js
+check "a nested path maps by relative path, not basename" 0 "orphans=0"
+
+reset_root
+make_src lib beta index.ts; make_out lib beta index.js
+make_src services gamma index.ts; make_out services gamma index.js
+check "lib and services trees are scanned too" 0 "trees=2"
+
+reset_root
+make_src plugins alpha index.ts; make_out plugins alpha index.js
+make_out plugins alpha lib/gone.js
+check "a compiled file whose source was deleted fails" 1 "orphan=plugins/alpha/mcp/dist/lib/gone.js"
+
+reset_root
+make_out lib deleted-project index.js; make_out lib deleted-project helper.js
+check "a dist whose whole project is gone is one project orphan" 1 "orphan-project=lib/deleted-project/dist"
+
+reset_root
+check "no dist tree at all fails rather than reporting a clean zero" 1 "trees=0"
+
+# --remove deletes exactly what it reported, and leaves the live file alone.
+reset_root
+make_src plugins alpha index.ts; make_out plugins alpha index.js
+make_out plugins alpha lib/gone.js
+printf '{}\n' > "$(fam_base plugins alpha dist)/lib/gone.js.map"
+REMOVE_OUT=$(node "$GATE" "$ROOT/platform" --remove 2>&1); REMOVE_EXIT=$?
+if [[ ! -e "$(fam_base plugins alpha dist)/lib/gone.js" \
+   && ! -e "$(fam_base plugins alpha dist)/lib/gone.js.map" \
+   && -f "$(fam_base plugins alpha dist)/index.js" ]]; then
+  echo "PASS: --remove deletes the orphan and its sidecars, keeps the live file"; PASS=$((PASS+1))
+else
+  echo "FAIL: --remove did not delete exactly the orphan set"; FAIL=$((FAIL+1))
+fi
+
+# The removal must report the state on disk afterwards, not that a delete ran.
+if printf '%s' "$REMOVE_OUT" | grep -qF -- "removed=1 remaining=0" && [[ "$REMOVE_EXIT" -eq 0 ]]; then
+  echo "PASS: --remove re-scans and reports the post-condition"; PASS=$((PASS+1))
+else
+  echo "FAIL: --remove did not re-scan — expected 'removed=1 remaining=0' and exit 0, got exit $REMOVE_EXIT"
+  printf '%s\n' "$REMOVE_OUT" | sed 's/^/      /'; FAIL=$((FAIL+1))
+fi
+
+echo "---"; echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/scripts/check-orphan-dist.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Reconciles every compiled output tree under platform/ against its sources.
+//
+// Why this is a standing check and not a log line: `tsc` never removes output
+// for a source that was deleted, and the bundler copies each tree — `dist`
+// included — into the payload that `npm publish` ships. The deletion emits no
+// event, and rebuilding does not surface the leftover, so nothing short of an
+// independent reconcile can see it.
+//
+// Every project compiles `rootDir: src` to `outDir: dist`, so `dist/<rel>.js`
+// maps to exactly one source, `src/<rel>.ts`. Two shapes of orphan exist:
+//   file    — the .ts was deleted, the project still exists. `tsc -b --clean`
+//             would remove it.
+//   project — the whole project was deleted; `dist` survives with no `src` and
+//             no tsconfig, so no tsc invocation can ever reach it. Reported
+//             once per directory rather than once per file.
+//
+// Usage: node check-orphan-dist.mjs [platformRoot] [--remove]
+// Exit 0 when every .js has a source. Exit 1 on any orphan, and exit 1 when no
+// dist tree was found at all — a zero-orphan pass must never be
+// indistinguishable from having measured nothing.
+//
+// With --remove it deletes exactly the set it just reported (each orphan .js
+// plus its .js.map/.d.ts/.d.ts.map sidecars; a project orphan's whole dist
+// directory) and then re-scans, so the exit code reflects the state on disk
+// afterwards rather than the fact that a delete was called. Sharing one rule
+// between the detector and the repair is what stops the two drifting apart.
+
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join, resolve, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const remove = args.includes("--remove");
+const rootArg = args.find((a) => !a.startsWith("--"));
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const platformRoot = resolve(rootArg ?? join(scriptDir, ".."));
+
+// Each family maps a project directory to its dist/src pair. `sub` is the
+// directory between the project and its dist/src, empty where there is none.
+const FAMILIES = [
+  { dir: "plugins", sub: "mcp" },
+  { dir: "lib", sub: "" },
+  { dir: "services", sub: "" },
+];
+
+function subdirs(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+function walkJs(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkJs(full, out);
+    else if (entry.name.endsWith(".js")) out.push(full);
+  }
+  return out;
+}
+
+function scan() {
+  let trees = 0;
+  let files = 0;
+  const fileOrphans = [];
+  const projectOrphans = [];
+
+  for (const family of FAMILIES) {
+    const familyDir = join(platformRoot, family.dir);
+    for (const project of subdirs(familyDir)) {
+      const base = family.sub
+        ? join(familyDir, project, family.sub)
+        : join(familyDir, project);
+      const distDir = join(base, "dist");
+      if (!existsSync(distDir)) continue;
+      trees += 1;
+      const srcDir = join(base, "src");
+      if (!existsSync(srcDir)) {
+        projectOrphans.push(distDir);
+        files += walkJs(distDir, []).length;
+        continue;
+      }
+      for (const js of walkJs(distDir, [])) {
+        files += 1;
+        const rel = js.slice(distDir.length + 1);
+        if (!existsSync(join(srcDir, `${rel.slice(0, -3)}.ts`))) fileOrphans.push(js);
+      }
+    }
+  }
+  return { trees, files, fileOrphans, projectOrphans, total: fileOrphans.length + projectOrphans.length };
+}
+
+const rel = (p) => relative(platformRoot, p);
+
+function report(r) {
+  console.log(`[orphan-dist] trees=${r.trees} files=${r.files} orphans=${r.total}`);
+  for (const p of r.projectOrphans) console.log(`[orphan-dist] orphan-project=${rel(p)}`);
+  for (const f of r.fileOrphans) console.log(`[orphan-dist] orphan=${rel(f)}`);
+}
+
+const first = scan();
+report(first);
+
+if (first.trees === 0) {
+  console.error(
+    "[orphan-dist] FATAL: no dist tree found under platform/{plugins,lib,services} — " +
+      "the check measured nothing rather than finding nothing. Build platform first.",
+  );
+  process.exit(1);
+}
+
+if (remove && first.total > 0) {
+  for (const dir of first.projectOrphans) rmSync(dir, { recursive: true, force: true });
+  for (const js of first.fileOrphans) {
+    const stem = js.slice(0, -3);
+    for (const ext of [".js", ".js.map", ".d.ts", ".d.ts.map"]) {
+      rmSync(`${stem}${ext}`, { force: true });
+    }
+  }
+  // Re-scan rather than trust the delete. The exit code must reflect what is
+  // on disk now, not the fact that rmSync was called.
+  const after = scan();
+  console.log(`[orphan-dist] removed=${first.total - after.total} remaining=${after.total}`);
+  if (after.total > 0) {
+    console.error(
+      `[orphan-dist] FATAL: ${after.total} orphan(s) survived removal. Check permissions on the ` +
+        "paths listed above.",
+    );
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (first.total > 0) {
+  console.error(
+    `[orphan-dist] FATAL: ${first.total} compiled output(s) have no source. Their .ts was deleted and ` +
+      "the compiler left the .js behind, where the bundler copies it into the published payload. " +
+      "Run `npm run clean:dist` in platform/ to remove exactly this set.",
+  );
+  process.exit(1);
+}

package/payload/platform/scripts/lib/agent-identity-reconcile.sh

@@ -0,0 +1,122 @@
+# agent-identity-reconcile.sh — converge every account's public-agent IDENTITY.md
+# against the shipped template, and state the divergence count.
+#
+# Task 2671. The re-sync this replaces lived inside provision_account_dir, and
+# setup-account.sh calls that for the house account and no other, so an agent
+# created on a client sub-account keeps whatever identity text it was seeded
+# with for ever. Measured on laptop 192.168.88.10 on 2026-08-11: the house
+# account's agents were refreshed by that morning's install while
+# `5bc2c0e2/agents/beagle` still carried the 2026-07-31 text and
+# `.../fares` the 2026-08-04 one, both of them telling a spawn that now holds
+# five tools that it holds none.
+#
+# This is the identity twin of account-settings-reconcile.sh, written the same
+# way and for the same reason, and it is the file's only writer: the in-place
+# loop was deleted when this landed.
+#
+# IDENTITY.md is Rubytech-controlled and copied verbatim (agent-write.ts:113), so
+# an operator edit here is drift to be corrected, not content to preserve. That
+# is the one place this diverges from the settings reconciler, which leaves an
+# unparseable file alone because it may carry an operator edit worth keeping.
+#
+# Idempotent. Never creates an agent dir, never writes SOUL/KNOWLEDGE/config,
+# never echoes file contents.
+#
+# Sourced by setup-account.sh; also runnable standalone for a manual repair.
+
+# ensure_agent_identity <identity_file> <template_file> <account_id> <agent_slug>
+# Returns 0 when the file already matched the template, 1 when it diverged, and
+# 2 when the copy landed empty. Logs exactly one
+#   [identity-reconcile] account=<id> agent=<slug> status=<already-current|updated|rewrite-failed|empty-after-copy|no-template>
+ensure_agent_identity() {
+  local f="$1" tpl="$2" acct="$3" slug="$4"
+
+  if [ ! -s "$tpl" ]; then
+    echo "[identity-reconcile] account=$acct agent=$slug status=no-template"
+    return 1
+  fi
+
+  if cmp -s "$f" "$tpl"; then
+    echo "[identity-reconcile] account=$acct agent=$slug status=already-current"
+    return 0
+  fi
+
+  if ! cp "$tpl" "$f" 2>/dev/null; then
+    echo "[identity-reconcile] account=$acct agent=$slug status=rewrite-failed"
+    return 1
+  fi
+
+  # A 0-byte cp traps the brand server in STARTING: the reachability auditor
+  # then reports `reachable=false reason=files-missing IDENTITY.md:empty` every
+  # minute and the operator sees the splash for ever. Observed on
+  # 192.168.88.16 after a re-install, source 1655 bytes and destination 0. This
+  # is the one condition the pass refuses to continue past, carried over from
+  # the loop it replaces.
+  if [ ! -s "$f" ]; then
+    echo "[identity-reconcile] account=$acct agent=$slug status=empty-after-copy" >&2
+    return 2
+  fi
+
+  # Divergent, like every other non-matching outcome: `divergent=` counts files
+  # this pass had to act on, so a run that rewrote one and a run that rewrote
+  # none are distinguishable in the summary line.
+  echo "[identity-reconcile] account=$acct agent=$slug status=updated"
+  return 1
+}
+
+# reconcile_all_accounts_identities <accounts_dir>
+# Standing check + durable backfill across every account carrying an
+# account.json. Emits one status line per agent plus one summary line on every
+# run, including a zero count — silence is not evidence of convergence, and
+# `agents=0` on an install that has accounts is a stopped counter rather than a
+# clean pass.
+#
+# Returns 1 only when a copy landed empty, so the caller aborts before the brand
+# server starts. Every other failure is reported and stepped over.
+reconcile_all_accounts_identities() {
+  local accts="$1"
+  local tpl="${MAXY_PUBLIC_IDENTITY_TEMPLATE:-${TEMPLATES_DIR:-}/agents/public/IDENTITY.md}"
+  local n=0 agents=0 divergent=0 fatal=0
+  local acct acct_id agent_dir slug rc
+
+  if [ -d "$accts" ]; then
+    for acct in "$accts"/*/; do
+      [ -f "$acct/account.json" ] || continue
+      n=$((n + 1))
+      acct_id="$(basename "$acct")"
+      for agent_dir in "$acct/agents"/*/; do
+        [ -d "$agent_dir" ] || continue
+        slug="$(basename "$agent_dir")"
+        # admin has its own Rubytech identity; passive has a third (Task 1483),
+        # and re-syncing either from the public visitor template would replace a
+        # correct prompt with the wrong one.
+        [ "$slug" = "admin" ] && continue
+        [ "$slug" = "passive" ] && continue
+        # Never create. An agent dir with no IDENTITY.md is a half-made agent,
+        # which agent-create's rollback already prevents; seeding one here would
+        # make it look whole.
+        [ -f "$agent_dir/IDENTITY.md" ] || continue
+        agents=$((agents + 1))
+        # `|| rc=$?` rather than a bare call followed by `rc=$?`: setup-account.sh
+        # runs under `set -e`, and a bare call returning non-zero kills the
+        # install the first time any agent diverges — which is every upgrade
+        # that has work to do. The `||` puts the call in a tested context, the
+        # same shape account-settings-reconcile.sh uses for the same reason.
+        rc=0
+        ensure_agent_identity "$agent_dir/IDENTITY.md" "$tpl" "$acct_id" "$slug" || rc=$?
+        # if-blocks rather than `[ … ] && …` lists: an AND-list whose test fails
+        # returns non-zero, and as the last command in this loop body that is
+        # another way `set -e` kills the install.
+        if [ "$rc" -ne 0 ]; then divergent=$((divergent + 1)); fi
+        if [ "$rc" -eq 2 ]; then fatal=1; fi
+      done
+    done
+  fi
+
+  echo "[identity-reconcile] accounts=$n agents=$agents divergent=$divergent"
+  if [ "$fatal" -eq 1 ]; then
+    echo "  [setup] FATAL a public IDENTITY.md is empty after copy from $tpl ($(wc -c < "$tpl" 2>/dev/null || echo 0) bytes); aborting before the brand server starts" >&2
+    return 1
+  fi
+  return 0
+}