@rubytech/create-realagent-code 0.1.574 → 0.1.576

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

@@ -27,27 +27,26 @@ The remote-access password is the *outer* gate — the password the Cloudflare t
 
 ## Channel bindings decide whether an answer reaches a second channel
 
-An admin's `users.json` entry carries two optional bindings, and they are what
-lets one answer reach every channel that person holds rather than only the one
-the message arrived on.
+An admin's `users.json` entry carries two optional bindings. They say who a
+sender is. They do not decide where an answer goes: an answer always goes back
+to the door the message arrived on and nowhere else.
 
-`phone` is the E.164 number. It identifies a WhatsApp sender as this person, and
-it is also the address used to reach them on WhatsApp when a turn arrives
-somewhere else. `telegram` is the chat id, matched exactly, doing the same two
-jobs for Telegram. They are not interchangeable, and two-way reach needs both.
+`phone` is the E.164 number, identifying a WhatsApp sender as this person.
+`telegram` is the chat id, matched exactly, doing the same for a Telegram
+sender. They are not interchangeable, and a person messaging from both channels
+needs both set to be recognised on both.
 
 `account.json` `whatsapp.adminPhones` is a different thing: an allowlist saying
 a number may reach the admin agent. It grants access; it does not say whose
 number it is, which is why adding a phone there never binds anyone.
 
-When a binding is missing, the failure is silent to the person messaging. These
+When a binding is missing, the sender is not recognised as this admin. These
 lines in `server.log` name it:
 
 | Line | Means |
 |---|---|
-| `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | this sender resolves to no admin, so no second door is looked for |
-| `[channel-fanout] op=no-target origin=… reason=no-admin-user` | the same fact, at the fan-out |
-| `[channel-fanout] op=fan-out reached=… notReached=…` | which doors actually received the answer |
+| `[whatsapp-native] op=admin-identity senderId=… userId=unbound-empty` | this sender resolves to no admin |
+| `[channel-fanout] op=fan-out reached=… notReached=…` | whether the door that wrote received the answer |
 
 A Telegram bot owned by a `role:'client'` sub-account can never resolve an
 admin: both resolvers return null on a client account before reading any chat

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

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

@@ -9,6 +9,18 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-08 (0.1.576)
+
+- Installing and upgrading no longer runs data conversions on your existing records. Five had accumulated, each added to repair a state that every install has long since passed, so all five did nothing but add work and risk to every upgrade. One of them stopped the install outright after reporting it had nothing to do. Any future conversion will be something you run deliberately, not part of an upgrade.
+
+## 2026-08-08 (0.1.575)
+
+- **Reverses one change from 0.1.574.** An answer now stays on the channel you asked from, rather than also being copied to your other channels. The copy arrived as a reply with no question above it, because only the answer travelled and not what you had asked; a WhatsApp question turned up in Telegram as a bare statement. Being reachable on more than one device is already handled per channel, so the copy was removed rather than completed.
+- You no longer get told a tool call is blocked when it is simply taking a while. Every long-running call was being reported as blocked and pushed to your channel.
+- Field and dispatch work is now usable end to end: an incoming request can be reviewed into a job instead of sitting in an unqueued pile, a site carries the address the worker needs to find it, allocation shows the travel time from the previous job, two workers on one visit are no longer indistinguishable from two separate visits, and pressing a button in Telegram now acts on the visit rather than sending a typed message.
+- A visit's start time is stored consistently, so a comparison against a time window is no longer an hour out during British Summer Time.
+- Two safeguards closed: a file the assistant was refused permission to copy across accounts could still land minutes later by another route with nothing recording it, and the outbound check that strips private paths did not know about the media directory now served on the public door.
+
 ## 2026-08-07 (0.1.574)
 
 - An answer meant for you now reaches every channel you have live, not just the one you asked from. That had never actually worked, and nothing reported it.

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-visits-scope.test.ts

@@ -19,7 +19,27 @@ interface Row {
  * that replayed rows would pass whatever the gate did, which is the same defect
  * shape as 1689's upload fake accepting duplicates the schema rejected.
  */
-function db(rows: Row[], person: { ownerId: string; recordScope: string; accountId: string }) {
+interface RosterFixture {
+  accountId: string
+  workerId: string
+  ownerId: string
+  name: string
+  workingHours: string
+}
+
+interface MetaFixture {
+  vocabulary: string
+  statuses: string
+  zone: string
+  publishedAt: string
+}
+
+function db(
+  rows: Row[],
+  person: { ownerId: string; recordScope: string; accountId: string },
+  roster: RosterFixture[] = [],
+  meta: MetaFixture | null = null,
+) {
   return {
     prepare(sql: string) {
       let bound: unknown[] = []
@@ -29,12 +49,21 @@ function db(rows: Row[], person: { ownerId: string; recordScope: string; account
           return stmt
         },
         async first<T>() {
+          // The session resolve and the meta read both use first(); branching on
+          // the table is what keeps the fake honest about which one answered.
+          if (sql.includes('FROM dispatch_meta')) return meta as unknown as T
           return person as unknown as T
         },
         async run() {
           return { meta: { changes: 0 } }
         },
         async all<T>() {
+          if (sql.includes('FROM visit_roster')) {
+            const [acct, owner] = bound as string[]
+            let out = roster.filter((r) => r.accountId === acct)
+            if (sql.includes('r.ownerId = ?')) out = out.filter((r) => r.ownerId === owner)
+            return { results: out as unknown as T[] }
+          }
           if (!sql.includes('FROM visits')) return { results: [] as T[] }
           const [acct, owner] = bound as string[]
           let out = rows.filter((r) => r.accountId === acct)
@@ -110,3 +139,103 @@ describe('the visits scope gate', () => {
     expect(lines.join('\n')).toContain('visits=1')
   })
 })
+
+const ROSTER: RosterFixture[] = [
+  {
+    accountId: 'acc-a',
+    workerId: 'w1',
+    ownerId: 'alice',
+    name: 'Alice Stone',
+    workingHours: '{"mon":["08:00","17:00"]}',
+  },
+  { accountId: 'acc-a', workerId: 'w2', ownerId: 'bob', name: 'Bob Reed', workingHours: '{}' },
+  {
+    accountId: 'acc-b',
+    workerId: 'w3',
+    ownerId: 'alice',
+    name: 'Another Alice',
+    workingHours: '{}',
+  },
+]
+
+const META: MetaFixture = {
+  vocabulary: '{"job":"job","visit":"visit","worker":"technician"}',
+  statuses: '[{"name":"new","terminal":false}]',
+  zone: 'Europe/London',
+  publishedAt: '2026-08-07T12:00:00.000Z',
+}
+
+describe('the roster and the config come back through the same gate', () => {
+  it('gives an account-scoped person every worker on their own account', async () => {
+    const h = await processVisits(
+      'sess',
+      env(db(ROWS, asPerson('marie', 'account'), ROSTER, META)),
+      () => {},
+      1,
+    )
+    expect(h.status).toBe(200)
+    expect((h.payload.roster as Array<{ workerId: string }>).map((w) => w.workerId).sort()).toEqual(
+      ['w1', 'w2'],
+    )
+  })
+
+  it('gives an own-scoped person only their own roster row, so the page is not a staff list', async () => {
+    const h = await processVisits(
+      'sess',
+      env(db(ROWS, asPerson('alice', 'own'), ROSTER, META)),
+      () => {},
+      1,
+    )
+    expect((h.payload.roster as Array<{ ownerId: string }>).map((w) => w.ownerId)).toEqual(['alice'])
+  })
+
+  it('parses workingHours out of its JSON column so the page never parses it', async () => {
+    const h = await processVisits(
+      'sess',
+      env(db(ROWS, asPerson('marie', 'account'), ROSTER, META)),
+      () => {},
+      1,
+    )
+    const roster = h.payload.roster as Array<{
+      workerId: string
+      workingHours: Record<string, string[]>
+    }>
+    expect(roster.find((w) => w.workerId === 'w1')!.workingHours.mon).toEqual(['08:00', '17:00'])
+  })
+
+  it('returns the zone and the nouns to both scopes, because they are config not personal data', async () => {
+    for (const scope of ['own', 'account']) {
+      const h = await processVisits(
+        'sess',
+        env(db(ROWS, asPerson('alice', scope), ROSTER, META)),
+        () => {},
+        1,
+      )
+      const m = h.payload.meta as { zone: string; vocabulary: { worker: string } }
+      expect(m.zone).toBe('Europe/London')
+      expect(m.vocabulary.worker).toBe('technician')
+    }
+  })
+
+  it('answers with an empty roster and a null meta when the account published none', async () => {
+    const h = await processVisits(
+      'sess',
+      env(db(ROWS, asPerson('marie', 'account'))),
+      () => {},
+      1,
+    )
+    expect(h.payload.roster).toEqual([])
+    expect(h.payload.meta).toBeNull()
+  })
+
+  it('survives a malformed JSON column rather than failing the whole week', async () => {
+    const broken = [{ ...ROSTER[0], workingHours: '{not json' }]
+    const h = await processVisits(
+      'sess',
+      env(db(ROWS, asPerson('marie', 'account'), broken, META)),
+      () => {},
+      1,
+    )
+    expect((h.payload.roster as Array<{ workingHours: unknown }>)[0].workingHours).toEqual({})
+  })
+})

package/payload/platform/plugins/cloudflare/skills/data-portal/schema.sql

@@ -340,3 +340,66 @@ CREATE TABLE IF NOT EXISTS visit_status (
 -- The pull selects unclaimed rows for one account every sixty seconds, so the
 -- pair carries its own index or every cycle is a full scan.
 CREATE INDEX IF NOT EXISTS visit_status_pending ON visit_status (accountId, claimed);
+
+-- One row per configured worker, per staging generation (Task 2539). The office
+-- planner draws a row per worker, including a worker with nothing on: an
+-- omitted row reads as a worker who does not exist.
+--
+-- `workerId` is the id in the account's own dispatch/config.json. `ownerId` is
+-- the enrolled portal person that worker signs in as, resolved by the push from
+-- an explicit `portalOwnerId` on the :Engineer carrying that engineerId, and ''
+-- when they carry none. The binding is a property and NEVER a name match, the
+-- same rule `visits.ownerId` above states: two people share a first name, and a
+-- silent cross-assignment shows one worker another's day.
+--
+-- A worker whose ownerId is '' still gets a row. They are visible to an
+-- account-scoped person, invisible to every own-scoped one, and counted by the
+-- push as `workers-unresolved`, so an unbound worker is found in the journal
+-- rather than by somebody opening an empty week.
+--
+-- `workingHours` is the JSON object from the config ({"mon":["08:00","17:00"]}).
+-- It is read as one unit by one consumer and never filtered on, so it is one
+-- column rather than a table that would need a migration per config field.
+--
+-- `generation` and the flip are the visits' own: this table is staged at the
+-- generation the visits push claims and becomes live through the SAME
+-- `visits_state` pointer, so the roster a week is drawn against and the week
+-- itself can never be one generation apart.
+CREATE TABLE IF NOT EXISTS visit_roster (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  accountId    TEXT NOT NULL,
+  workerId     TEXT NOT NULL,
+  ownerId      TEXT NOT NULL DEFAULT '',
+  name         TEXT NOT NULL DEFAULT '',
+  workingHours TEXT NOT NULL DEFAULT '',
+  generation   INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (accountId, workerId, generation)
+);
+
+CREATE INDEX IF NOT EXISTS visit_roster_account ON visit_roster (accountId);
+
+-- One row per account, per staging generation: the configuration the planner
+-- renders itself from (Task 2539).
+--
+-- `vocabulary` and `statuses` are JSON straight off the account's
+-- dispatch/config.json, so a taxi firm's fare/pickup/driver and a contractor's
+-- job/visit/engineer render through one page with no operator-facing literal in
+-- its source.
+--
+-- `zone` is the account's own timezone, resolved on the device. The page formats
+-- every date in it and never consults the browser's: a browser-zone fallback
+-- renders plausibly and wrongly, which is the defect Task 2280 left on thirteen
+-- other surfaces.
+--
+-- `publishedAt` is when this generation was staged, so the page can state the
+-- age of what it shows. A mirror that stopped refreshing is otherwise identical
+-- to a week with no changes.
+CREATE TABLE IF NOT EXISTS dispatch_meta (
+  accountId   TEXT NOT NULL,
+  vocabulary  TEXT NOT NULL DEFAULT '',
+  statuses    TEXT NOT NULL DEFAULT '',
+  zone        TEXT NOT NULL DEFAULT '',
+  publishedAt TEXT NOT NULL DEFAULT '',
+  generation  INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (accountId, generation)
+);

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/visits.ts

@@ -19,6 +19,53 @@ export interface VisitRow {
   purpose: string
 }
 
+/**
+ * One configured worker, as the office planner draws a row for (Task 2539).
+ *
+ * `workerId` is the id in the account's own dispatch config; `ownerId` is the
+ * enrolled portal person that worker signs in as, and '' when they have no
+ * binding. The page groups visits onto rows by `ownerId`, which is the key both
+ * halves of the exchange already use.
+ */
+export interface RosterRow {
+  workerId: string
+  ownerId: string
+  name: string
+  workingHours: Record<string, [string, string]>
+}
+
+/**
+ * The configuration the planner renders itself from, and the age of what it
+ * shows.
+ *
+ * Null when the account has published none, which is every portal carrying no
+ * dispatch config. Null rather than an empty object: a page that renders
+ * defaults for a missing config states an account's nouns wrongly instead of
+ * saying it has none.
+ */
+export interface Meta {
+  vocabulary: { job: string; visit: string; worker: string }
+  statuses: Array<{ name: string; terminal: boolean }>
+  zone: string
+  publishedAt: string
+}
+
+/**
+ * A column of JSON text, or the fallback.
+ *
+ * Never a throw. One malformed value must not take a whole week off the screen:
+ * the worker's row still renders with no hours, which is visibly wrong, where a
+ * 500 is indistinguishable from the device being down.
+ */
+function parseJson<T>(raw: string, fallback: T): T {
+  try {
+    const v = JSON.parse(raw) as T
+    return v === null || v === undefined ? fallback : v
+  } catch {
+    return fallback
+  }
+}
+
 /**
  * The visits a signed-in person may read.
  *
@@ -67,13 +114,67 @@ export async function processVisits(
   const rows = await bound.all<VisitRow>()
   const visits = rows.results ?? []
 
+  // THE SAME TWO FILTERS, and the owner one for the same reason: an own-scoped
+  // person may see their own row and no other, or this page becomes a way to
+  // read colleague names that the file drop deliberately does not give them.
+  // Read through the generation pointer, as the visits read is.
+  const rosterSql =
+    `SELECT r.workerId AS workerId, r.ownerId AS ownerId, r.name AS name,
+            r.workingHours AS workingHours
+       FROM visit_roster r
+       JOIN visits_state s
+         ON s.accountId = r.accountId AND s.currentGeneration = r.generation
+      WHERE r.accountId = ?` +
+    (scoped ? ' AND r.ownerId = ?' : '') +
+    ' ORDER BY r.name ASC, r.workerId ASC'
+  const rosterStmt = env.DB.prepare(rosterSql)
+  const rosterRows = await (
+    scoped
+      ? rosterStmt.bind(env.PORTAL_ACCOUNT_ID, session.ownerId)
+      : rosterStmt.bind(env.PORTAL_ACCOUNT_ID)
+  ).all<{ workerId: string; ownerId: string; name: string; workingHours: string }>()
+
+  // Parsed here, once, rather than on the page: a column of JSON parsed by every
+  // consumer is a shape each of them can disagree about.
+  const roster: RosterRow[] = (rosterRows.results ?? []).map((r) => ({
+    workerId: r.workerId,
+    ownerId: r.ownerId,
+    name: r.name,
+    workingHours: parseJson<Record<string, [string, string]>>(r.workingHours, {}),
+  }))
+
+  const metaRow = await env.DB.prepare(
+    `SELECT m.vocabulary AS vocabulary, m.statuses AS statuses, m.zone AS zone,
+            m.publishedAt AS publishedAt
+       FROM dispatch_meta m
+       JOIN visits_state s
+         ON s.accountId = m.accountId AND s.currentGeneration = m.generation
+      WHERE m.accountId = ?`,
+  )
+    .bind(env.PORTAL_ACCOUNT_ID)
+    .first<{ vocabulary: string; statuses: string; zone: string; publishedAt: string }>()
+
+  // NOT owner-scoped. The nouns, the statuses and the account's timezone are
+  // configuration, not a record about a person, and the page cannot draw a day
+  // in the right zone without them.
+  const meta: Meta | null = metaRow
+    ? {
+        vocabulary: parseJson(metaRow.vocabulary, { job: '', visit: '', worker: '' }),
+        statuses: parseJson<Array<{ name: string; terminal: boolean }>>(metaRow.statuses, []),
+        zone: metaRow.zone,
+        publishedAt: metaRow.publishedAt,
+      }
+    : null
+
   // Counts and the scope, never a visitId or a purpose: those are a real
-  // person's job, and a Pages log is not where they belong.
+  // person's job, and a Pages log is not where they belong. A worker's NAME is
+  // the same kind of thing, so the roster contributes a count too.
   log(
     `[data-portal] op=visits owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
-      `scope=${session.recordScope} visits=${visits.length} result=ok`,
+      `scope=${session.recordScope} visits=${visits.length} roster=${roster.length} ` +
+      `meta=${meta !== null} result=ok`,
   )
-  return { status: 200, payload: { ok: true, visits } }
+  return { status: 200, payload: { ok: true, visits, roster, meta } }
 }
 
 interface PagesContext {

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

@@ -1,6 +1,6 @@
 {
   "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.",
+  "description": "Field-work dispatch. Holds an inbound request as a reviewable draft, creates a job when somebody approves it, allocates it to a qualified worker with an estimate of how far each candidate has to come, moves it through the account's own configured statuses, sends the worker the card he presses to move it, 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-intake-draft, dispatch-intake-decide, dispatch-intake-list, dispatch-site-upsert, dispatch-site-location-set, dispatch-job-create, dispatch-job-get, dispatch-job-list, dispatch-allocate-candidates, dispatch-allocate, dispatch-visit-status-set, dispatch-visit-record, dispatch-site-history, dispatch-day and dispatch-notify-worker. Ships the dispatch-setup skill, which elicits and validates the config, and the dispatch-page skill, which puts the account's week planner on its own portal domain.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"