@rubytech/create-maxy-code 0.1.571 → 0.1.573

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

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:021d3690d7d8100b010cc7d9669e51707f501b5be58dac2399a2d751ca9844e1
+content-hash: sha256:5b9f6de800b201bf45e5d433a707987b4d09c6fb7d552240158afb2f73a3600f
 brand: maxy-code
 product-name: Maxy
 ---
@@ -696,6 +696,170 @@ You can also ask for that check on demand at any time, and it reports the same t
 
 If you never see the line at all, that is itself the problem: it means the periodic check is not running.
 
+---
+# Dispatch
+Source: https://docs.getmaxy.com/dispatch.md
+
+# Dispatch
+
+Field-work dispatch: create a job, allocate it to a qualified worker, move it through the account's
+own statuses, record what happened on site. Admin agent only, ten tools, ships inert.
+
+## Enabling it
+
+`dispatch` is in `plugins.available` on all four brands and in `defaultEnabled` on none. An account
+adds it to `enabledPlugins`, then runs the `dispatch-setup` skill to author
+`$ACCOUNT_DIR/dispatch/config.json`. Until that file exists and validates, every tool registers and
+refuses per call with `reason=no-config`.
+
+Enabling it also puts `schema-dispatch.md` in the account's resolved verticals, beside
+`schema-base` and the account's own businessType vertical. That is what makes `:Job`, `:Visit`,
+`:Site`, `:Customer`, `:Asset`, `:Part`, `:JobCost`, `:Contact`, job `:Note` and `:Engineer`
+writable from any businessType rather than from construction alone.
+
+## The config is the vocabulary and the rules
+
+Six keys in `$ACCOUNT_DIR/dispatch/config.json`: `statuses` (job and visit lists, each entry
+`{name, terminal}`, plus `jobTransitions` and `visitTransitions` as explicit `[from, to]` pairs),
+`jobTypes` (`{name, requiredQualification, defaultDurationMin, slaTargetHours?}`), `workers`
+(`{workerId, name, qualifications[], workingHours}`), `records` (`checklists` per job type,
+`requiredBeforeTerminal` per terminal visit status), `vocabulary` (`job`, `visit`, `worker`), and
+`vehicles` (`{enabled, defaultGeofenceRadiusM?}`).
+
+No status, job type, qualification, checklist, SLA target or operator noun appears in plugin source.
+A test walks every source file and fails if any string from either shipped fixture config appears in
+it.
+
+## The ten tools
+
+| Tool | Does | Refuses when |
+|---|---|---|
+| `dispatch-config-get` | Returns the vocabulary, statuses, transitions, job types, roster, checklists and the config audit | no config |
+| `dispatch-job-create` | Raises a job at a site for a customer, in the account's first job status, with `slaTargetAt` computed from the type | unknown job type; site or customer does not exist |
+| `dispatch-job-get` | One job with every visit, its times, who attended and what was recorded | job not on this account |
+| `dispatch-job-list` | Jobs filtered by status, type, worker, date window, or narrowed to never-allocated. `overdue` computed on every read | status not declared |
+| `dispatch-allocate-candidates` | Who could take this job in this window, with clashes shown and exclusions named | job unknown, untyped, or typed to something no longer declared |
+| `dispatch-allocate` | Creates the visit, attends it, moves the job along its own edge, attaches a vehicle | worker not on the roster; worker lacks the qualification; vehicle passed while `vehicles.enabled` is false; no `:Person:Engineer` node for the workerId |
+| `dispatch-visit-status-set` | Moves a visit; closes the job when its last visit reaches a terminal status | status not declared; transition not in the edge list; a required record missing |
+| `dispatch-visit-record` | Note, media reference, fitted part, checklist item, signature, arrival | visit unknown; nothing supplied to record |
+| `dispatch-site-history` | Every visit at one site, newest first, with notes | — |
+| `dispatch-day` | One day: every worker with the visits they hold, plus jobs nobody has been sent to | — |
+
+All ten are `adminAllowlist: true`, `publicAllowlist: false`.
+
+## Legality is data
+
+A move is legal when the account's own transition list contains that `[from, to]` pair. There is no
+state machine in the code. A refusal names both ends:
+`op=transition-refused … from=X to=Y reason=not-in-config`.
+
+A move into a terminal status is refused a second way when the visit is missing a field
+`records.requiredBeforeTerminal` demands there, and that refusal names the field:
+`reason=missing-required-field:notes`.
+
+Neither refusal is swallowed. A status that quietly failed to change cannot be told apart from one
+nobody tried to change.
+
+## A busy worker is offered, not hidden
+
+Only a missing qualification excludes a worker, and every exclusion is named:
+`exclusions=w1:missing-qualification`. A qualified worker already committed in the window is offered
+with the clash shown. Double-booking is the office's decision, and a tool that drops the busy option
+makes that decision for them with no trace.
+
+There is no travel-time estimate.
+
+## Arrival is two properties
+
+`arrivedPressedAt` and `arrivedObservedAt` are written by separate `SET` clauses, so recording
+either never clears the other. An observation with no press is stored and flagged. A pressed arrival
+is what somebody said; an observed one is what was measured, and a single `arrivedAt` cannot show
+them disagreeing.
+
+## The standing checks
+
+Six failure modes emit no event, because no action occurs: a job created and never allocated, a job
+past its SLA target, a status no transition reaches, a job type no worker is qualified for, a worker
+with no qualification, and visits closing hours after the work ended.
+
+- `[dispatch-census]`, per account, every 15 minutes: `jobs= unallocated= oldestUnallocatedAgeH=
+  overdue= visitsOpen= visitsOpenOver24h=`
+- `[dispatch-config-audit]`, on config load and each tick: `statuses= unreachable= terminal=
+  jobTypes= typesWithNoQualifiedWorker= workersWithNoQualification=`
+- `[dispatch-record-census]`, daily: `closedVisits= withNote= withMedia= medianRecordLagS=
+  p90RecordLagS=`
+
+They run in the UI server, not in the plugin, because a plugin only runs when somebody calls it.
+Accounts without a dispatch config are skipped silently.
+
+`overdue` is the count a typical incumbent system reports as zero because response-time targets were
+never configured. A non-zero, believable number is the feature working.
+
+The absence of `[dispatch-census]` is itself the signal: the check died, and every count is stale
+rather than zero.
+
+## The office planner
+
+`/dispatch` is an admin surface that renders a dispatch day: worker rows against days over a
+selectable range, a job list with true counts, and each visit's status with its pressed and
+observed arrival side by side. It reads; it does not yet re-time or re-allocate.
+
+It does not call these tools. Both it and this plugin read through `platform/lib/dispatch-read`,
+which owns its Neo4j session, so the planner's route holds no graph credentials and issues no
+Cypher — asserted by a test rather than trusted. This plugin's `mcp/src/lib/read.ts` is a
+re-export of that lib, so the tools and the planner cannot disagree about what a filter means.
+
+Two things the planner computes for itself. `dispatch-day` bounds a day in UTC, which misplaces a
+Europe/London visit near local midnight for the whole of British Summer Time, so the planner
+derives boundaries in the account's own timezone. And `dispatch-job-list` caps its rows, so the
+planner takes its counts from an aggregate instead of counting what it was given.
+
+It also names a defect it cannot fix. `dispatch-allocate` stores `startDate` exactly as the caller
+passed it (`allocate.ts:186`) while normalising `endDate` (`allocate.ts:51`). The window compare is
+lexical, so a start carrying a non-UTC offset reads correctly under GMT and an hour out under
+British Summer Time. The planner logs `op=nonzulu-start` with the offending visit ids; correcting
+it belongs at the writer.
+
+Full detail: [`.docs/dispatch-planner.md`](../../../.docs/dispatch-planner.md).
+
+## The field job sheet
+
+The engineer's surface is his phone, so the detailed record is made in a Telegram Mini App: the sheet
+opens inside the chat he is already in, with nothing installed and no second login.
+
+Set it up once per bot:
+
+1. Run `telegram-menu-button` with the bot's token and the account's public https origin. Give the
+   origin only — the tool appends `/field` and stamps the bot id on itself.
+2. Give each worker in `dispatch/config.json` a `telegramUserId` matching their numeric Telegram id.
+   Without one the sheet refuses them with "Ask the office to add you as an engineer."
+
+The worker then taps the menu button and sees today's visits, in the order they will be done, each
+card carrying the site, the customer, the contact and what was reported. Opening one shows the
+site's previous visits with their notes and photograph counts, then the checklist for that job type,
+parts, both signatures and a free note. Completion is refused, naming the one missing field, when
+the account's `requiredBeforeTerminal` is not satisfied.
+
+Every refusal is named and none of them shows a login form. `unbound-user` is the office's to fix;
+`bad-hash` and `duplicate-bot` mean something is wrong rather than missing.
+
+Two limits worth knowing before you deploy it. There is no offline queue yet, so an edit made out of
+signal is refused rather than held; the sheet says so rather than appearing to save it. And a site
+carries no address, because the ontology has none to carry, so a card names the site but cannot give
+a street. `sitesVisitedTodayWithoutAddress=` on the census counts what that costs each day. Both are
+tracked work, not permanent limits.
+
+Full detail: [`.docs/dispatch-field-app.md`](../../../.docs/dispatch-field-app.md).
+
+## Diagnostic path
+
+```
+journalctl --user -u <brand>-* | grep -E '\[dispatch\]|\[dispatch-census\]|\[dispatch-config-audit\]|\[dispatch-record-census\]|\[dispatch-field\]|\[dispatch-field-census\]'
+```
+
+Then filter by `jobId=` for one job's lifeline, `op=transition-refused` to audit rejected writes, or
+`exclusions=` to see why allocation offered whom.
+
 ---
 # Install Overview
 Source: https://docs.getmaxy.com/install.md
@@ -1797,59 +1961,27 @@ JSONL and the real follower.
 | `whatsapp-channel/src/server.ts:620` | `consumedInbounds <= 0` (2nd follower) | `no-consumed-inbound` |
 
 ```
-[<door>-channel]     op=turn-drop sessionId=… messageId=… finalBytes=… reason=…
-[<door>-turn-census] op=census sessionId=… pending=… held=<0|1> heldMessageId=… heldAgeMs=… lastMessageId=…
+[channel-fanout] op=fan-out reached=… notReached=… segments=… messageId=… sessionId=…
+[channel-parity] op=parity-census sessionId=… rendered=… sent=… missing=… missingIds=…
 ```
 
-Any `op=turn-drop` with `finalBytes>0` is a lost answer. The census runs every
-60 s per follower; `held=1` with `heldAgeMs` rising across ticks is a hold that
-never resolved, and `pending` not returning to 0 with no inbound in flight is
-credit drift.
+`missing` above zero is a lost answer, and `missingIds` names each one. The
+census prints every cycle, including when the counts agree: an absent line means
+the census stopped, never that delivery is healthy.
 
-**Read them in the right file.** Both lines are emitted by the *channel MCP
-server*, whose stderr is teed to `${LOG_DIR}/mcp-<serverName>-<sessionId>.log`
-(`claude-session-manager/src/channel-spawn-tee.ts`). They are **never** in
-`server.log`, which carries the gateway-side half only — `op=turn-end`,
-`op=turn-answer-absent`, `delivered=`. Grepping `server.log` for a drop returns
-nothing and means nothing.
+**Read them in `server.log`.** Both are emitted by the ui-server, which now owns
+the one emitter between the session JSONL and every channel. The per-door
+`op=turn-drop` and `op=census` lines that used to sit in
+`${LOG_DIR}/mcp-<serverName>-<sessionId>.log` are gone with the per-channel
+followers that were removed, and so is `delivered=fallback`, which no code
+emits.
 
 ```bash
-# the discard and the hold, per session
-grep -E 'op=(turn-drop|census)' ~/.<brand>/logs/mcp-telegram-channel-*.log | tail -20
-# the gateway's view of the same turn
-grep -E 'op=(turn-end|turn-answer-absent)' ~/.<brand>/logs/server.log | grep <sessionId>
+# every answer and where it went
+grep -E 'op=(fan-out|parity-census)' ~/.<brand>/logs/server.log | tail -20
+# one session
+grep 'op=fan-out' ~/.<brand>/logs/server.log | grep <sessionId>
 ```
-
-**A seventh discard site, and the one nothing was reading.** An answer that
-survived every guard above could still be produced and thrown away at the last
-step, because the gateway resolved its destination from admin identity rather
-than from the channel it came in on. A public visitor has no admin identity, so
-the resolver returned no target: nothing was attempted, no transport failed, and
-the line read `reached=none notReached=none`.
-
-The turn-end body now carries the channel server's own spawn `role`, and that is
-the only thing that decides the destination:
-
-| `role=` | Where the answer goes | `op=fan-out` |
-|---|---|---|
-| `public` | every segment through the posting key's own transport; no identity resolver, no registry read | never emitted |
-| `admin` | every live door the person is reachable on, via `fanTargetsFor` | emitted |
-| absent or unrecognised | nowhere. 400, plus one `op=turn-role-absent … evicted=<yes\|no>` | never emitted |
-
-`op=turn-end` and `op=turn-strand-anomaly` both name the role, so no outcome is
-unattributable.
-
-A roleless POST has one cause: a channel server from a build predating the field,
-still attached to a session that outlived the platform restart. It reconnects its
-stream, so nothing respawns it, and left alone it would post roleless turn-ends for
-the life of that session. `evicted=yes` says the gateway dropped its subscriber, so
-the next inbound spawns a server on the current build: one turn is lost per session
-rather than all of them. That turn's answer is deliberately not delivered to the
-posting key, because doing so would restore the very fallback whose reachability hid
-the original defect. The standing check is one line per door per minute, over a
-rolling hour:
-
-```bash
 # the standing read; any undeliveredPublic>0 is a failure
 grep -E 'op=census' ~/.<brand>/logs/server.log | grep delivery-census | tail -5
 # a visitor's answer that reached nobody, or a turn-end that named no role
@@ -2653,6 +2785,29 @@ Two things to know:
 Text only for now. Photos, files and voice notes are not available on Telegram
 from the dashboard.
 
+## Building your own Telegram functionality
+
+Telegram is a core plugin, so it is on every install and cannot be switched off.
+
+Beyond sending and reading messages, Maxy can reach every one of the
+185 things Telegram's Bot API can do: buttons under a message, changing a
+message after you sent it, uploading a photo or a document, pinning, polls, chat
+administration, and opening a small web page inside the Telegram chat itself.
+
+Just ask for what you want. "Send the team a message with Yes and No buttons",
+"update that job card to say he's on site", "pin the rota to the group".
+Maxy loads its Telegram build skill, which lists every available
+method and how to call it.
+
+Five of the 185 are deliberately refused, because they would break your own
+inbound messages: setting or deleting the webhook by hand, polling Telegram for
+updates instead, and the two that move the bot off Telegram's cloud servers.
+Setting up or repointing a webhook is what the Telegram setup skill is for.
+
+If Telegram publishes a new capability it works here immediately, with nothing
+released first. A scheduled check reconciles what Maxy knows about
+against Telegram's live documentation and reports anything that changed.
+
 ---
 # Outlook
 Source: https://docs.getmaxy.com/outlook-guide.md

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

@@ -9,6 +9,22 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-07 (0.1.573)
+
+- One piece of the platform now sends every answer to every channel, instead of each channel deciding for itself. A standing check compares what the conversation record holds against what was actually sent, so a missing message is reported rather than noticed.
+- A healthy conversation sitting idle is no longer mistaken for a stuck one and shut down. A recovered conversation now also re-sends the answer it was holding.
+- Your second message in an admin webchat reaches the conversation you are already in. It was being addressed to a name the running conversation had never subscribed to, so it could report a delivery failure and then arrive twice.
+- A file the assistant sends you now opens. The download link was refused for anyone outside the account that produced it, so the link returned a not-found.
+- Telegram now supports far more of what the service can do, rather than the four operations it exposed before.
+- A routine that is switched off by a check now stops waking the assistant, and the check that woke it is recorded. The audits behind those checks now report somewhere that is actually read.
+- Sending an email draft no longer reports success when the step before it was refused, which could send the same message twice.
+
+## 2026-08-07 (0.1.572)
+
+- A new dispatch planner in the admin gives the office a week-grid view of each worker's day with per-day state and standing divergence checks.
+- Field workers get a Telegram Mini App job sheet with today's visits, edit-in-place, storage-probe writes, and a `[dispatch-field-census]` reconciling who should be working against who has been heard from.
+- The dispatch write path is now a shared `dispatch-write` lib behind a domain outcome, and the sheet is styled and served correctly on public hosts.
+
 ## 2026-08-06 (0.1.571)
 
 - Telegram no longer drops inbound messages that are not plain text: voice notes are transcribed into the turn text, and a live location renders as a single track on the map that fits its own viewport.

package/payload/platform/plugins/dispatch/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "dispatch",
+  "description": "Field-work dispatch. Creates a job, allocates it to a qualified worker, moves it through the account's own configured statuses, and records what happened on site. Every status, job type, qualification, checklist, SLA target and operator-facing noun is read from $ACCOUNT_DIR/dispatch/config.json, never hard-coded, so a taxi firm's fare/pickup/driver and a contractor's job/visit/engineer run identical code. Provides dispatch-config-get, dispatch-job-create, dispatch-job-get, dispatch-job-list, dispatch-allocate-candidates, dispatch-allocate, dispatch-visit-status-set, dispatch-visit-record, dispatch-site-history and dispatch-day. Ships the dispatch-setup skill, which elicits and validates the config.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "dispatch": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/lib/mcp-spawn-tee/index.js",
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ],
+      "env": {
+        "MCP_SPAWN_TEE_NAME": "dispatch"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,116 @@
+---
+name: dispatch
+description: "Field-work dispatch. Creates a job, allocates it to a qualified worker, moves it through the account's own configured statuses, and records what happened on site. Every status, job type, qualification, checklist, SLA target and operator-facing noun is read from $ACCOUNT_DIR/dispatch/config.json, never hard-coded, so a taxi firm's fare/pickup/driver and a contractor's job/visit/engineer run identical code. Provides dispatch-config-get, dispatch-job-create, dispatch-job-get, dispatch-job-list, dispatch-allocate-candidates, dispatch-allocate, dispatch-visit-status-set, dispatch-visit-record, dispatch-site-history and dispatch-day. Ships the dispatch-setup skill, which elicits and validates the config."
+tools:
+  - name: dispatch-config-get
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
+  - name: dispatch-job-create
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: write_local
+  - name: dispatch-job-get
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
+  - name: dispatch-job-list
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
+  - name: dispatch-allocate-candidates
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
+  - name: dispatch-allocate
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: write_local
+  - name: dispatch-visit-status-set
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: write_local
+  - name: dispatch-visit-record
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: write_local
+  - name: dispatch-site-history
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
+  - name: dispatch-day
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
+always: false
+embed: false
+metadata: {"platform":{}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/dispatch/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: dispatch
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    ACCOUNT_DIR: ${ACCOUNT_DIR}
+    SESSION_ID: ${SESSION_ID}
+    AGENT_SLUG: ${AGENT_SLUG}
+mcp-manifest: auto
+---
+
+# Dispatch
+
+A write path for field work. Admin agent only.
+
+## What it does and does not do
+
+It creates a job at a site for a customer, offers the workers who could take it, sends one of them, moves the job and its visits through the statuses this account declared, and records what happened on site: notes, photos, parts fitted, checklist items, signatures, and when the worker arrived.
+
+It does not price work, invoice it, optimise a route, or generate a planned-maintenance schedule. It holds no intake queue and estimates no travel time; both are separate work. It creates no site, customer, worker or vehicle — it refuses when one of those is missing rather than inventing it, because a job pointing at a site nobody has heard of is worse than no job.
+
+## Nothing an operator can name is in the source
+
+`$ACCOUNT_DIR/dispatch/config.json` carries six keys: the job and visit statuses with the legal moves between them, the job types with the qualification each needs, the worker roster with what each holds, the checklists and what a visit must carry before it closes, the words this operator uses, and whether vehicles are assigned.
+
+A test walks every source file in this plugin and fails if any string from either shipped fixture config appears in it. That is the mechanism behind the claim, not a convention. Both fixtures — an electrical contractor and a taxi firm — share no status, job type, qualification or noun, and the same suite drives both from creation to a terminal status.
+
+## Legality is data
+
+A move from one status to another is legal when the account's own transition list contains that pair, and refused otherwise. There is no state machine in the code. The refusal names both ends, so `op=transition-refused … from=X to=Y reason=not-in-config` says exactly what was attempted and why it did not happen. A move into a terminal status is refused a second way when the visit is missing a field the account requires there, and that refusal names the field.
+
+Neither refusal is swallowed. A status that quietly failed to change cannot be told apart from one nobody tried to change.
+
+## A busy worker is offered, not hidden
+
+Only a missing qualification excludes a worker from the candidate list, and every exclusion is named with its worker and its reason. A qualified worker who is already committed in the window is offered with the clash shown.
+
+Double-booking is the office's decision. A tool that silently drops the busy option makes that decision for them and leaves no trace that it was made.
+
+## Arrival is two observations
+
+`:Visit` carries `arrivedPressedAt` and `arrivedObservedAt` as separate properties, written by separate clauses. Recording either never clears the other, and an observation with no press is stored and flagged rather than dropped.
+
+A pressed arrival is what somebody said; an observed one is what was measured. The reference account had one worker close a Monday's jobs on Tuesday morning, so every recorded finish time was when a button was pressed. A single `arrivedAt` cannot show that; two that disagree can.
+
+## The standing checks
+
+Six ways this can fail emit no event at all, because no action occurs: a job created and never allocated, a job past its SLA target, a status no transition reaches, a job type no worker is qualified for, a worker with no qualification recorded, and visits closing hours after the work ended.
+
+None can be caught by logging an action. Three standing lines cover them, emitted by the UI server rather than by this plugin, because a plugin only runs when somebody calls it:
+
+- `[dispatch-census]`, per account, every 15 minutes: job counts, unallocated count and the age of the oldest, overdue count, open visits and those open over 24 hours.
+- `[dispatch-config-audit]`, on config load and each census tick: status and job-type counts, unreachable statuses, job types with no qualified worker, workers with no qualification.
+- `[dispatch-record-census]`, daily: closed visits, how many carry a note or a photo, and the median and 90th-percentile lag between work ending and the record being written.
+
+`overdue` is the count the reference account's incumbent system reports as zero, because its response-time targets were never configured. A non-zero and believable number here is the feature working, not a fault.
+
+The absence of `[dispatch-census]` is itself the signal: it means the check died and every count above is stale rather than zero.
+
+## Ships inert
+
+The plugin is in `plugins.available` on all four brands and in `defaultEnabled` on none. An account switches it on, and a second account on the same install is unaffected. Until `$ACCOUNT_DIR/dispatch/config.json` exists, every tool registers and refuses per call with `reason=no-config`, naming the setup skill. Module init reads no per-account environment and never throws, because plugin-system spawn enumerates tools with empty environment and one boot throw would empty the registry for every plugin.
+
+Enabling the plugin also puts `schema-dispatch.md` in the account's resolved verticals, beside `schema-base` and the account's own businessType vertical. That is what makes the field-service labels reachable from any businessType rather than construction alone.

package/payload/platform/plugins/dispatch/lib/mcp-spawn-tee/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MCP spawn-tee — in-process stderr capture + lifecycle observability.
+ *
+ * Claude Code spawns each MCP server itself; the platform never holds a
+ * ChildProcess handle. This shim sits between Claude Code and the real MCP
+ * server: Claude Code runs `node <this> <real-entry>`, and the shim runs the
+ * real entry IN ITS OWN PROCESS via dynamic import() — one node runtime, not
+ * two. Before importing, it replaces process.stderr.write with a tee so every
+ * stderr byte the server writes is mirrored to the log sinks; stdin and stdout
+ * (the JSON-RPC channel) are never touched.
+ *
+ *   Claude Code CLI → shim (this file) = node running <real-entry> in-process
+ *        stdin/stdout : untouched (JSON-RPC channel)
+ *        stderr       : process.stderr.write teed → raw sink + passthrough
+ *
+ * Destinations:
+ *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — raw stderr + lifecycle lines.
+ *     The sole raw sink. Task 1721 retired the per-date twin: its date was
+ *     pinned at spawn, no reader ever parsed it, and a since-removed stderr
+ *     tee wrote the same file, so every line landed twice.
+ *   - `${LOG_DIR}/mcp-<name>-nosession.log`      — the same, for a spawn with
+ *     no SESSION_ID (enumeration). One fixed file per server.
+ *   - `server.log` via the loopback log-ingest route — best-effort mirror of
+ *     the [mcp-helper] lifecycle lines.
+ *
+ * Lifecycle lines, correlation key `session=<id8> server=<name>` — unchanged:
+ *   [mcp-helper] op=spawn ... pid= entry=
+ *   [mcp-helper] op=boot  ... head=<first stderr bytes>
+ *   [mcp-helper] op=exit  ... code= signal= lifetimeMs= stderr-tail=
+ *
+ * Process model (Task 989): the shim IS the server's process. op=exit fires
+ * from process.on("exit"), so it covers a normal exit, a non-zero exit, an
+ * uncaught throw (code 1), and a catchable-signal exit (SIGTERM/SIGINT/SIGHUP,
+ * whose handlers record the signal name). An external SIGKILL is uncatchable
+ * and leaves no op=exit line — the per-session stderr tail already on disk and
+ * Claude Code's own transport-drop are the evidence for that death mode.
+ *
+ * The shim never writes to fd 1 (stdout) — that is the JSON-RPC channel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const SESSION_ID = process.env.SESSION_ID;
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
+const ENTRY = process.argv[2];
+const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
+const spawnStamp = Date.now();
+// The one raw sink (Task 1721). A sessionless spawn (rc-daemon stamps
+// SESSION_ID='' — rc-daemon.ts:513 — while still stamping LOG_DIR) shares one
+// fixed file per server rather than a date-named one: the date was never read
+// by any reader and named a process lifetime, not a day. Interleaved spawns in
+// the nosession file are separated by the [mcp-helper] op=spawn pid= lines.
+const rawSinkPath = LOG_DIR
+    ? (0, node_path_1.resolve)(LOG_DIR, SESSION_ID ? `mcp-${SERVER_NAME}-${SESSION_ID}.log` : `mcp-${SERVER_NAME}-nosession.log`)
+    : undefined;
+// Rolling tail of entry stderr for op=exit. Capped so a chatty server cannot
+// grow the buffer without bound.
+const TAIL_CAP = 2048;
+let stderrTail = "";
+let bootEmitted = false;
+let exitEmitted = false;
+let exitSignal;
+// The real stderr writer, captured before the tee replaces it. Lifecycle lines
+// and stderr passthrough both go through this so they are never re-teed into
+// the raw sink nor recursed back into the patched writer.
+const rawStderrWrite = process.stderr.write.bind(process.stderr);
+// LOG_DIR is created once, lazily, on the first successful append — not per
+// chunk. teeWrite runs on the server's own stderr hot path now, so a per-call
+// mkdirSync would be two syscalls per log line for nothing.
+let logDirReady = false;
+function appendSafe(path, data) {
+    if (!path || !LOG_DIR)
+        return;
+    try {
+        if (!logDirReady) {
+            (0, node_fs_1.mkdirSync)(LOG_DIR, { recursive: true });
+            logDirReady = true;
+        }
+        (0, node_fs_1.appendFileSync)(path, data);
+    }
+    catch {
+        /* unwritable destination — never mask primary output */
+    }
+}
+// Best-effort mirror of a lifecycle line to server.log via the loopback
+// log-ingest route. Fire-and-forget: the per-session file is authoritative, so
+// a dropped POST loses nothing. On the "exit" event the loop is stopping, so
+// the op=exit mirror may not flush — the per-session line, written sync, holds.
+function postToServerLog(suffix, level) {
+    if (!PLATFORM_PORT)
+        return;
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 500);
+        t.unref?.(); // never let the abort timer keep the shim's event loop alive
+        void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ tag: "mcp-helper", level, line: suffix }),
+            signal: ctrl.signal,
+        }).then(() => clearTimeout(t)).catch(() => clearTimeout(t));
+    }
+    catch {
+        /* fetch threw synchronously — best-effort only */
+    }
+}
+// Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
+// survives process.exit), the shim's own stderr via the RAW writer (journald /
+// Claude Code visibility, never re-teed), and a best-effort server.log mirror.
+// `suffix` is the line body after the tag and carries no newline (the
+// log-ingest route rejects newlines).
+function emitLifecycle(suffix, level) {
+    const line = `[mcp-helper] ${suffix}\n`;
+    appendSafe(rawSinkPath, line);
+    try {
+        rawStderrWrite(line);
+    }
+    catch { /* stderr closed */ }
+    postToServerLog(suffix, level);
+}
+if (!ENTRY) {
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
+    process.exit(2);
+}
+// Replace process.stderr.write with a tee: mirror every server stderr byte to
+// the raw sink, keep a rolling tail for op=exit, emit
+// op=boot on the first bytes, then pass the write through to the real stderr.
+const teeWrite = ((...args) => {
+    const chunk = args[0];
+    appendSafe(rawSinkPath, chunk); // raw sink (Task 1721)
+    const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    stderrTail = (stderrTail + text).slice(-TAIL_CAP);
+    if (!bootEmitted) {
+        bootEmitted = true;
+        const head = text.split("\n")[0].slice(0, 200);
+        emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+    }
+    return rawStderrWrite(...args); // passthrough
+});
+process.stderr.write = teeWrite;
+// Catchable-signal handling. The shim drives the exit ONLY when it is the sole
+// listener for the signal — i.e. the imported entry installed no handler of its
+// own. In that case it records the signal (so op=exit carries signal=<sig>) and
+// exits with 128+signum, mirroring the prior wrapper's exit-status convention.
+//
+// When the entry DID install a handler, the shim defers entirely and records
+// nothing: the entry's handler decides the exit code, and op=exit reflects that
+// exit verbatim. This matches the prior two-process model, where a child that
+// caught the signal and exited cleanly was observed as code=0 signal=— (a clean
+// self-exit), not as a signal death. Setting exitSignal here unconditionally
+// would mislabel every graceful signal-driven shutdown as a signal kill.
+function onSignal(sig, code) {
+    return () => {
+        if (process.listenerCount(sig) === 1) {
+            exitSignal = sig;
+            process.exit(code);
+        }
+    };
+}
+process.on("SIGTERM", onSignal("SIGTERM", 143));
+process.on("SIGINT", onSignal("SIGINT", 130));
+process.on("SIGHUP", onSignal("SIGHUP", 129));
+// op=exit, emitted once from the process "exit" event. Sync-only — the loop is
+// stopping. When a catchable signal caused the exit, report code=— signal=<sig>
+// to match the prior wrapper's format; otherwise code=<exit code> signal=—.
+process.on("exit", (code) => {
+    if (exitEmitted)
+        return;
+    exitEmitted = true;
+    const lifetimeMs = Date.now() - spawnStamp;
+    const tail = stderrTail.slice(-200);
+    const codeField = exitSignal ? "—" : String(code);
+    const level = exitSignal || code !== 0 ? "error" : "info";
+    emitLifecycle(`op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} ` +
+        `code=${codeField} signal=${exitSignal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level);
+});
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} entry=${ENTRY}`, "info");
+// Task 2356 — present argv as a direct `node <entry>` invocation before the
+// entry loads. The shim is meant to be transparent: an entry that asks the
+// standard "am I the entry module?" question
+// (`import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href`)
+// must get the same answer it gets when Claude Code runs it without the shim.
+// With the shim's own path left in argv[1] the answer is no, so such an entry
+// loads, starts nothing, and exits 0 — measured on the three channel servers,
+// which all gate main() that way. Plugin MCPs connect at module top level and
+// never read argv, so this is inert for them. ENTRY was captured above, before
+// the rewrite. Extra CLI args keep their positions after the entry slot.
+process.argv = [process.argv[0], ENTRY, ...process.argv.slice(3)];
+// Run the real MCP server in THIS process. Dynamic import() (not top-level
+// await — this file compiles to CommonJS) loads the ESM entry; a load-time
+// failure mirrors the old child spawn-error path (op=error, exit 127). The
+// op=exit handler is suppressed on this path so op=error stays the sole record.
+import((0, node_url_1.pathToFileURL)(ENTRY).href).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    exitEmitted = true;
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`import error: ${msg}`)}`, "error");
+    process.exit(127);
+});
+//# sourceMappingURL=index.js.map