@rubytech/create-maxy-code 0.1.552 → 0.1.554

package/payload/platform/lib/routine-templates/src/index.ts

@@ -166,7 +166,20 @@ export async function resolveOwnerTimezone(
  *  destroy the operator's own caption on the next version bump; and the
  *  scheduling plugin's one-shot `converge-routine-description` has already given
  *  every pre-existing row a description, so no row is left holding only a
- *  title. */
+ *  title.
+ *
+ *  The gate (Task 2379) is written by a `SET` after the MERGE rather than inside
+ *  either branch, because both branches need `e.eventId` and only one of them
+ *  has just minted it. `writing` is the same condition the prompt follows, so a
+ *  gate is written on create, refreshed on a version bump of an unedited row,
+ *  and never touched on an operator-edited one.
+ *
+ *  Two details are load-bearing. The null branch is symmetric on purpose: a
+ *  template reclassified gateless must have its three properties cleared, or the
+ *  row keeps a gate its template no longer declares and nothing reports it. And
+ *  the commit token is substituted from the same `row.gateChecks` the gate is
+ *  built from, so the precondition and the turn's own commit call cannot
+ *  disagree about what this routine checks. */
 export const MERGE_CYPHER = `
 UNWIND $rows AS row
 OPTIONAL MATCH (pre:Event {accountId: $accountId, routineTemplate: row.key})
@@ -202,6 +215,13 @@ MERGE (e:Event {accountId: $accountId, routineTemplate: row.key})
                e.description = CASE WHEN refreshing THEN row.description ELSE e.description END,
                e.routineTemplateVersion = CASE WHEN refreshing THEN $version ELSE e.routineTemplateVersion END,
                e.updatedAt = CASE WHEN refreshing THEN $now ELSE e.updatedAt END
+WITH row, e, existed, priorVersion, edited, (NOT existed OR refreshing) AS writing
+SET e.gatePlugin = CASE WHEN writing THEN (CASE WHEN row.gateChecks IS NULL THEN null ELSE 'scheduling' END) ELSE e.gatePlugin END,
+    e.gateTool = CASE WHEN writing THEN (CASE WHEN row.gateChecks IS NULL THEN null ELSE 'scheduling-gate' END) ELSE e.gateTool END,
+    e.gateArgs = CASE WHEN writing THEN (CASE WHEN row.gateChecks IS NULL THEN null ELSE '{"eventId":"' + e.eventId + '","checks":' + row.gateChecks + '}' END) ELSE e.gateArgs END,
+    e.agentPrompt = CASE WHEN writing AND row.gateChecks IS NOT NULL
+                         THEN replace(e.agentPrompt, '<<gateCommit>>', '{"eventId":"' + e.eventId + '","checks":' + row.gateChecks + ',"commit":true}')
+                         ELSE e.agentPrompt END
 RETURN row.key AS key,
        e.eventId AS eventId,
        CASE WHEN NOT existed THEN 'create'
@@ -277,6 +297,10 @@ export async function seedRoutineRoster(args: SeedRoutineRosterArgs): Promise<Ro
       description: r.description,
       prompt: r.prompt,
       recurrence: r.recurrence,
+      // Task 2379 — the only place the checks are serialised. Null for a
+      // gateless template, which the MERGE reads as "clear the three gate
+      // properties on the write path".
+      gateChecks: r.gate ? JSON.stringify(r.gate.checks) : null,
     })),
   });
 

package/payload/platform/lib/routine-templates/src/roster.ts

@@ -35,7 +35,76 @@
  *  routine's prompt only when the stored `routineTemplateVersion` is BELOW this
  *  and no operator has edited the row, so an unbumped edit ships to new installs
  *  and never reaches existing ones — bump it in the same commit as the edit. */
-export const ROUTINE_TEMPLATE_VERSION = 2;
+export const ROUTINE_TEMPLATE_VERSION = 3;
+
+/**
+ * Task 2379 — the check shapes a shipped template may name.
+ *
+ * Declared here rather than imported from the scheduling plugin:
+ * `routine-templates` is a `platform/lib` package and importing from
+ * `platform/plugins` would invert the dependency direction and break the lib
+ * build, which has no plugin on its path. The roster test reads the tool's own
+ * source and asserts every type used here is one the tool declares, which is the
+ * same drift control this file already applies to tool names.
+ */
+export interface RoutineMailCheck {
+  readonly type: "mail";
+  readonly mailbox: string;
+  readonly folder?: string;
+  readonly subjectPrefixes?: readonly string[];
+}
+export interface RoutineD1Check {
+  readonly type: "d1";
+  readonly database: string;
+  readonly sql: string;
+}
+export interface RoutineWhatsappCheck {
+  readonly type: "whatsapp";
+  readonly scope: "inbound" | "status";
+}
+export interface RoutineCalendarCheck {
+  readonly type: "calendar";
+  readonly connector: string;
+}
+export type RoutineGateCheck =
+  | RoutineMailCheck
+  | RoutineD1Check
+  | RoutineWhatsappCheck
+  | RoutineCalendarCheck;
+
+/** The plugin and the tool are constants for every roster gate, so a template
+ *  carries neither. `hasWork` is true when ANY check is true. */
+export interface RoutineGate {
+  readonly checks: readonly RoutineGateCheck[];
+}
+
+/** Substituted by the seed with the full `scheduling-gate` argument object,
+ *  including the row's own event id.
+ *
+ *  A template cannot write that id: it is minted by the MERGE. Nor can the turn
+ *  supply it, because the only place a scheduled turn sees its own event is the
+ *  provenance preamble, which carries the first eight characters. The watermark
+ *  file is named from the whole id, so a turn committing against the prefix
+ *  would write a file the next gate never reads and the routine would report
+ *  work for ever. */
+export const GATE_COMMIT_TOKEN = "<<gateCommit>>";
+
+/** True when the check compares against a stored position rather than reading a
+ *  current one.
+ *
+ *  A watermarked check reads its stored value or zero, so with no watermark file
+ *  it reports work on every fire until something commits: such a gate is inert
+ *  until its routine's prompt carries the commit line. Mirrors `probe`'s `mark`
+ *  field in the scheduling plugin's `tools/scheduling-gate.ts`, which is a
+ *  function for exactly these three and null for the other two. */
+export function isWatermarkedCheck(check: RoutineGateCheck): boolean {
+  if (check.type === "whatsapp") return check.scope === "inbound";
+  return check.type === "mail" || check.type === "calendar";
+}
+
+export function gateNeedsCommit(gate: RoutineGate): boolean {
+  return gate.checks.some(isWatermarkedCheck);
+}
 
 export interface RoutineTemplate {
   /** Stable identity. Half of the MERGE key `(accountId, routineTemplate)`, so
@@ -54,6 +123,31 @@ export interface RoutineTemplate {
   readonly recurrence: string;
   /** The injected turn. Refreshed on a version bump when the row is unedited. */
   readonly prompt: string;
+  /** Task 2379 — the precondition, present when this routine's work is
+   *  conditional AND the check vocabulary can express its source without
+   *  per-account data. Seeded onto `gatePlugin`/`gateTool`/`gateArgs` under the
+   *  same rule the prompt follows: written on create, refreshed only on a
+   *  version bump of an unedited row. */
+  readonly gate?: RoutineGate;
+  /** Why this template ships with no gate. Exactly one of `gate` and `gateless`
+   *  is present on every template, and the roster test fails one carrying
+   *  neither, so a template added later cannot skip the decision. A field rather
+   *  than a comment because a comment cannot be asserted. */
+  readonly gateless?: string;
+}
+
+/** A template is classified when it carries exactly one of `gate` and a
+ *  non-empty `gateless`.
+ *
+ *  The rule lives here, in one function, rather than inline in the assertion
+ *  that walks the roster. A predicate the test only ever feeds passing input
+ *  reports clean while checking nothing, so the roster test asserts this both
+ *  ways: true for all thirteen, and false for a template carrying neither, both
+ *  and an empty reason. */
+export function isClassified(template: RoutineTemplate): boolean {
+  const gated = template.gate != null;
+  const declaredGateless = typeof template.gateless === "string" && template.gateless.trim() !== "";
+  return gated !== declaredGateless;
 }
 
 const START_OF_DAY = `Prepare the operator's morning briefing and reply with it as a single message.
@@ -128,7 +222,9 @@ An appointment on the provider calendar with no counterpart in the graph is invi
 
 If the account has a busy-time sync configured, run schedule-connector-busy-sync so availability reflects what was just reconciled.
 
-Reply only when something was actually changed, naming what and why. A clean reconcile ends the turn without replying, every time. This routine runs often, so a message on every clean run trains the operator to ignore it.`;
+Reply only when something was actually changed, naming what and why. A clean reconcile ends the turn without replying, every time. This routine runs often, so a message on every clean run trains the operator to ignore it.
+
+When the run has finished and nothing failed, call scheduling-gate with <<gateCommit>> so the next run does not re-examine what you have just reconciled. Do not call it after a run that failed or that you stopped early: the work would be marked as handled without anyone having seen it.`;
 
 const CONTACT_RECONCILE = `Reconcile the people the business actually deals with against the people it has recorded.
 
@@ -231,6 +327,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Sends one morning message covering what needs a decision, what is time-bound and what changed overnight; stays silent when there is nothing worth saying.",
     recurrence: "30 7 * * 1-5",
     prompt: START_OF_DAY,
+    gateless: "A morning briefing is judgement every fire, so a gate would either always pass or suppress the briefing.",
   },
   {
     key: "inbound-check",
@@ -239,6 +336,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Triages mail that arrived since the last check and writes replies for you to approve; it never sends anything itself.",
     recurrence: "*/30 9-17 * * 1-5",
     prompt: INBOUND_CHECK,
+    gateless: "Conditional on new mail, but the mail check matches an exact mailbox address and no shipped template can name one (Task 2389).",
   },
   {
     key: "end-of-day",
@@ -247,6 +345,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Closes the day with your unsent drafts, overdue work and tomorrow's diary; says nothing when all three are empty.",
     recurrence: "0 18 * * 1-5",
     prompt: END_OF_DAY,
+    gateless: "A wrap-up is judgement every fire, so no cheap check stands in for reading the three surfaces it reports.",
   },
   {
     key: "appointment-reminder",
@@ -255,6 +354,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reminds each attendee once before a booked appointment, on a route they already use; it never opens a conversation with a stranger.",
     recurrence: "0 * * * *",
     prompt: APPOINTMENT_REMINDER,
+    gateless: "Conditional on an appointment falling in the window, but no check type reads appointments held in the graph (Task 2389).",
   },
   {
     key: "commitment-chase",
@@ -263,6 +363,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Surfaces promises the business made and did not keep, and promises made to it that nobody kept; it reports them rather than chasing them.",
     recurrence: "0 10 * * 2",
     prompt: COMMITMENT_CHASE,
+    gateless: "Whether a promise has been dropped is the judgement itself, so no check can answer it more cheaply.",
   },
   {
     key: "calendar-reconcile",
@@ -271,6 +372,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reconciles the provider calendar against the appointments held in the graph, writing what is missing and marking what was cancelled; a clean run says nothing.",
     recurrence: "*/15 * * * *",
     prompt: CALENDAR_RECONCILE,
+    gate: { checks: [{ type: "calendar", connector: "account" }] },
   },
   {
     key: "contact-reconcile",
@@ -279,6 +381,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reconciles the people you correspond with against the people on record, creating and updating contacts; it never merges two records that might be two people.",
     recurrence: "45 6 * * 1-5",
     prompt: CONTACT_RECONCILE,
+    gateless: "Conditional on new correspondence, but no check type reads correspondence (Task 2389).",
   },
   {
     key: "crm-reconcile",
@@ -287,6 +390,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Brings across what changed in whichever operational system this business runs; it reads only and never writes back to that system.",
     recurrence: "0 3 * * *",
     prompt: CRM_RECONCILE,
+    gateless: "Conditional on connector movement, but no check type reads a connector queue (Task 2389).",
   },
   {
     key: "finance-reconcile",
@@ -295,6 +399,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reconciles the accounting system against the internal ledger and reports what does not agree; it never adjusts an entry to make the two sides match.",
     recurrence: "0 4 * * 1",
     prompt: FINANCE_RECONCILE,
+    gateless: "Conditional on accounting movement, but no check type reads an accounting ledger (Task 2389).",
   },
   {
     key: "weekly-digest",
@@ -303,6 +408,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Writes the week in three paragraphs at most: what changed, what is stuck, and what next week turns on.",
     recurrence: "0 16 * * 5",
     prompt: WEEKLY_DIGEST,
+    gateless: "A digest is judgement every fire, and a gate would suppress the report it exists to send.",
   },
   {
     key: "channel-link-check",
@@ -311,6 +417,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reports a messaging link that has gone down and whether it can recover on its own; it never disconnects a link or starts a re-pair.",
     recurrence: "*/15 * * * *",
     prompt: CHANNEL_LINK_CHECK,
+    gate: { checks: [{ type: "whatsapp", scope: "status" }] },
   },
   {
     key: "graph-health",
@@ -319,6 +426,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reports what the hourly graph sweep last did and what is waiting for review; it reads only and never runs the sweep itself.",
     recurrence: "0 9 * * 1",
     prompt: GRAPH_HEALTH,
+    gateless: "Reports the sweep's state every fire by design, so there is nothing conditional to check.",
   },
   {
     key: "filesystem-health",
@@ -327,6 +435,7 @@ export const ROUTINE_ROSTER: readonly RoutineTemplate[] = [
       "Reports what has grown under the account directory and which paths are worth attention; it deletes nothing.",
     recurrence: "0 9 * * 1",
     prompt: FILESYSTEM_HEALTH,
+    gateless: "Reports what has grown every fire by design, so there is nothing conditional to check.",
   },
 ];
 

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:b20c0cc4943d42c84f0e324403b1da911481214c3834ff2c778daf1f5f6db086
+content-hash: sha256:1d79dbcab9f7eb842df0e53078ed706535c2be25329f49a6c2592429417783da
 brand: maxy-code
 product-name: Maxy
 ---
@@ -3484,15 +3484,23 @@ The Routines surface (`/routines`) is the admin view of the account's
 automation `:Event` nodes — the device's scheduled agent turns and tool
 dispatches, which the Calendar surface deliberately excludes (`calendar.ts`
 unions only appointment events, `actionPlugin IS NULL`). It renders one card per
-routine (title, its one-line description where it has one, human-readable
-schedule, next run, channel/destination or tool, status); a card opens a detail
-modal modeled on the calendar `EventDetailModal`. A shipped routine is seeded with
-a description and the operator can rewrite it from the modal; a routine nobody has
-captioned renders with no line and no placeholder. Editing it stamps the row
+routine (title, human-readable schedule, its one-line description where it has
+one, next run, channel/destination or tool, status); a card opens a detail
+modal modeled on the calendar `EventDetailModal`.
+
+Every card on the page is the same height, whatever its description says. The
+title takes its own row and truncates to one line with an ellipsis, with the
+full text on hover and in the modal; the schedule reads directly beneath it; the
+description is clamped to three lines; and the status line is pinned to the
+card's bottom edge, so a column of cards shares one baseline for "Next:".
+
+A shipped routine is seeded with a name and a description, and the operator can
+rewrite either from the modal; a routine nobody has captioned renders with no
+description line and no placeholder. Editing either stamps the row
 operator-owned, so the next roster refresh leaves the operator's wording alone,
 and recomputes the row's search vector, which is built from the name and the
-description. A description is never dispatched: `agentPrompt` is the only text a
-fire sends.
+description together. A description is never dispatched: `agentPrompt` is the
+only text a fire sends.
 The read-only view shows two prose blocks, each under its own heading, in the
 order **Description** then **Instruction sent to the agent**. Both use the same
 header-above-prose shape, so neither reads as a different kind of thing from the
@@ -3511,7 +3519,10 @@ daily/weekly/monthly, day-of-week, day-of-month, time) that falls back to a
 raw-cron field for patterns it cannot represent. The binding control appears on
 an agent routine and on a routine with no dispatch at all; a tool-action
 routine's dispatch stays read-only, because an agent binding takes precedence at
-fire time and would stop the tool running.
+fire time and would stop the tool running. The **Name** box is the first field
+in the edit form: it is bounded at 200 characters, Save is blocked while it is
+empty, and renaming stamps the row operator-owned so the next roster version
+bump cannot put the seeded name back.
 
 **The status dot.** The card and the modal each carry a dot ahead of
 the raw status word, so a grid of eight routines can be read without reading
@@ -3525,8 +3536,8 @@ render it through one `RoutineStatusDot`, which is what stops them drifting:
 | `cancelled`, `completed` | solid grey (`--text-tertiary`) | deliberately stopped or finished |
 | anything else, and `null` | grey ring, no fill | no reading taken |
 
-**The run recap.** Each card carries a history icon that opens that routine's
-run history; the detail modal's **Runs** button reaches the same view. A run
+**The run recap.** The detail modal's **Runs** button opens that routine's run
+history, and it is the only way in: the card face carries no control. A run
 shows what it sent — the message text itself, on the row and in full in the run
 dialog — and a run that finished having sent nothing says so, which is a
 different statement from a run whose outcome is not yet known. Both the routine

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-03 (0.1.554)
+
+- You can now rename a routine from its detail view, and your name is kept when the built-in list is next refreshed.
+- Routine cards are now equal height with the title on its own row and past runs reached from the detail view rather than the card face.
+- The sidebar menu can now be collapsed to an icon rail, and your choice is remembered.
+
+## 2026-08-03 (0.1.553)
+
+- Each routine now shows how it runs, what its precondition checks, and how often it fired in the last day, so a routine that skipped can be told apart from one that ran quietly.
+- Every built-in routine is now classified as gated or ungated, and a new recurring routine has to answer that question rather than defaulting to waking on the clock.
+- Changing how often a routine runs is now recorded with its cost difference, and the rate across the install is counted on each check.
+
 ## 2026-08-02 (0.1.552)
 
 - A recurring routine can now check a condition first, so the clock alone no longer wakes the assistant when there is nothing to do. A one-time reminder is never gated, since skipping it would lose it.

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -99,15 +99,23 @@ The Routines surface (`/routines`) is the admin view of the account's
 automation `:Event` nodes — the device's scheduled agent turns and tool
 dispatches, which the Calendar surface deliberately excludes (`calendar.ts`
 unions only appointment events, `actionPlugin IS NULL`). It renders one card per
-routine (title, its one-line description where it has one, human-readable
-schedule, next run, channel/destination or tool, status); a card opens a detail
-modal modeled on the calendar `EventDetailModal`. A shipped routine is seeded with
-a description and the operator can rewrite it from the modal; a routine nobody has
-captioned renders with no line and no placeholder. Editing it stamps the row
+routine (title, human-readable schedule, its one-line description where it has
+one, next run, channel/destination or tool, status); a card opens a detail
+modal modeled on the calendar `EventDetailModal`.
+
+Every card on the page is the same height, whatever its description says. The
+title takes its own row and truncates to one line with an ellipsis, with the
+full text on hover and in the modal; the schedule reads directly beneath it; the
+description is clamped to three lines; and the status line is pinned to the
+card's bottom edge, so a column of cards shares one baseline for "Next:".
+
+A shipped routine is seeded with a name and a description, and the operator can
+rewrite either from the modal; a routine nobody has captioned renders with no
+description line and no placeholder. Editing either stamps the row
 operator-owned, so the next roster refresh leaves the operator's wording alone,
 and recomputes the row's search vector, which is built from the name and the
-description. A description is never dispatched: `agentPrompt` is the only text a
-fire sends.
+description together. A description is never dispatched: `agentPrompt` is the
+only text a fire sends.
 The read-only view shows two prose blocks, each under its own heading, in the
 order **Description** then **Instruction sent to the agent**. Both use the same
 header-above-prose shape, so neither reads as a different kind of thing from the
@@ -126,7 +134,10 @@ daily/weekly/monthly, day-of-week, day-of-month, time) that falls back to a
 raw-cron field for patterns it cannot represent. The binding control appears on
 an agent routine and on a routine with no dispatch at all; a tool-action
 routine's dispatch stays read-only, because an agent binding takes precedence at
-fire time and would stop the tool running.
+fire time and would stop the tool running. The **Name** box is the first field
+in the edit form: it is bounded at 200 characters, Save is blocked while it is
+empty, and renaming stamps the row operator-owned so the next roster version
+bump cannot put the seeded name back.
 
 **The status dot.** The card and the modal each carry a dot ahead of
 the raw status word, so a grid of eight routines can be read without reading
@@ -140,8 +151,8 @@ render it through one `RoutineStatusDot`, which is what stops them drifting:
 | `cancelled`, `completed` | solid grey (`--text-tertiary`) | deliberately stopped or finished |
 | anything else, and `null` | grey ring, no fill | no reading taken |
 
-**The run recap.** Each card carries a history icon that opens that routine's
-run history; the detail modal's **Runs** button reaches the same view. A run
+**The run recap.** The detail modal's **Runs** button opens that routine's run
+history, and it is the only way in: the card face carries no control. A run
 shows what it sent — the message text itself, on the row and in full in the run
 dialog — and a run that finished having sent nothing says so, which is a
 different statement from a run whose outcome is not yet known. Both the routine

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

@@ -105,6 +105,24 @@ is planned; until it ships, the internal calendar plus `.ics` import is the clie
 
 Automatic connector-to-internal availability sync is separate future work.
 
+## Reflecting a connector calendar into the booking page
+
+`schedule-connector-busy-sync` replaces this account's stored connector-busy set. Call it with **no
+arguments**: it resolves the account's own authorised connector from its token store, reads the next
+15 days of free/busy from that connector, and syncs. Nothing about that is a judgement, so nothing
+about it needs you — the tool spawns the google or outlook plugin's own free/busy tool to do the
+reading, and it is safe to invoke from a scheduled `action` dispatch with `args: {}`.
+
+An account with no authorised connector syncs `connector='none'` with an empty set. That is a
+success, not a failure: it clears a deauthorised connector's stale blocks.
+
+A failed read is an error and writes nothing. The stored busy set survives a transient provider
+outage, because publishing the operator's booked time as free is worse than not syncing at all.
+
+Passing `connector` and `busy` together is the explicit form and behaves exactly as before. Passing
+`busy` without `connector` is refused, because the connector tag is what a later sync compares
+against and it cannot be guessed from the intervals.
+
 ## Meetings vs events — what `schedule-event` writes
 
 `schedule-event` writes one of two graph nodes, decided from the parameters you pass — never from keywords in the title:
@@ -268,17 +286,45 @@ Users and plugins both create events with actions via the same `schedule-event`
 
 ## Agent-bearing dispatch
 
-An `action` invokes one pre-encoded MCP tool with no reasoning. When a due event needs an agent to decide what to do and say — "when this document is signed, work out what to tell me and message me on WhatsApp" — pass `agentDispatch` instead. When the event fires, the heartbeat hands the prompt to the destination's native channel: the channel spawns or resumes the deterministic admin session for that phone or chat, the agent runs the prompt with full admin tools, and its answer is delivered back over the account's paired socket. No operator session need be open.
+Choosing a dispatch mode is **two questions, not one**: should this fire run *at all*, and what should it *say* once it does. Answer them separately. A routine that needs a model to compose its message very often needs no model at all to decide whether there is anything to compose, and treating those as one question is how a conditional sweep ends up spawning a full agent turn every fifteen minutes to discover there was nothing to do.
+
+1. **`action`** — nothing here needs a model. One pre-encoded MCP tool, no reasoning, no spawn.
+2. **`agentDispatch` with a `gate`** — a model is needed to compose or to judge, but only when there is something to act on. **This is the default for anything conditional.** The dispatcher calls the gate tool headlessly before spawning; `hasWork:false` skips the fire entirely.
+3. **`agentDispatch` with no gate** — judgement applies on *every* fire, whatever the state of the world: a daily briefing, a weekly digest. This is the exception, and it is stated as one. A recurring `agentDispatch` with no `gate` is refused unless it carries `gateWaived` naming why.
+
+When an agent-bearing event fires, the heartbeat hands the prompt to the destination's native channel: the channel spawns or resumes the deterministic admin session for that phone or chat, the agent runs the prompt with full admin tools, and its answer is delivered back over the account's paired socket. No operator session need be open.
+
+The worked example is the second shape. The signature check is a gate; the prompt keeps only the composing and the messaging:
 
 ```json
-{ "channel": "whatsapp", "destination": "+447700900123", "prompt": "Check whether the tenancy agreement is signed yet and, if it is, message me a one-line confirmation." }
+{
+  "agentDispatch": {
+    "channel": "whatsapp",
+    "destination": "+447700900123",
+    "prompt": "The tenancy agreement has just been signed. Write the one-line confirmation and send it."
+  },
+  "gate": {
+    "plugin": "scheduling",
+    "tool": "scheduling-gate",
+    "args": {
+      "eventId": "<this event's id>",
+      "checks": [{ "kind": "d1", "database": "<the account's database>", "sql": "SELECT count(*) FROM agreements WHERE signed_at > '<watermark>'" }]
+    }
+  }
+}
 ```
 
+Written as one model turn instead — "check whether it is signed yet and, if it is, message me" — the check runs inside the spawned agent, so the turn costs a full agent run on every fire whether or not anything was signed.
+
 - `channel` — `whatsapp` or `telegram`.
 - `destination` — the E.164 phone (WhatsApp) or chat id (Telegram) to run the turn for and reply to. It **must already be a registered admin or account-manager** on that channel; a destination that is not is rejected when the event is created. For WhatsApp the authoritative admin/manager lists are read from the socket-owning **house** account (never the event's own account), and the destination's registered account must match the account that created the schedule: an admin belongs to the house, a manager to its bound sub-account. The house/owner account may target any registered admin or manager; a sub-account is locked to its own manager(s). A refusal names the true reason — `not-registered` (in no house list) or `cross-account` (registered to a different account, naming both accounts).
-- `prompt` — the instruction the agent runs.
+- `prompt` — the instruction the agent runs. Write it for the case where there **is** work: the gate has already decided that.
+- `gate` — `{ plugin, tool, args }`. The precondition, evaluated headlessly between the `nextRun` advance and the spawn. It must return `structuredContent {hasWork:boolean}`; the dispatcher reads that boolean and nothing else. A gate that errors, times out or returns no boolean **dispatches anyway**, so a broken check never silently mutes a routine. Requires a complete `agentDispatch`, and is refused on an action-mode event.
+- `gateWaived` — a string reason, and the only way to create a recurring `agentDispatch` with no gate. Give the reason this routine has judgement to apply on every fire ("the morning briefing composes from scratch each day"). It is stored on the event and counted by the standing gate-classification check, so a deliberate exception stays readable and the fleet's drift back to ungated is a number someone can look at. A conditional sweep is not an exception; gate it.
+
+**Recurring only.** A one-time agent event is never gated — its row is already `due` by the time the dispatcher sees it, so a skip there would drop the routine for good — and it is therefore outside the refusal. `schedule-update` takes no waiver either: an existing routine keeps what it has until it is edited.
 
-An event carries **either** an `action` **or** an `agentDispatch`, never both — setting one clears the other. Agent dispatch is stored as `agentChannel`, `agentDestination`, `agentPrompt`. Use `schedule-update` with `agentDispatch` to modify or `agentDispatch: null` to clear. On WhatsApp, a destination bound as an account-manager scopes the spawned session to its sub-account — unless that same phone is also on the house `adminPhones` list, in which case it scopes to the channel account, because the dispatch rides the house socket and so arrives from the house number. On Telegram the session runs on the house account.
+An event carries **either** an `action` **or** an `agentDispatch`, never both — setting one clears the other. Agent dispatch is stored as `agentChannel`, `agentDestination`, `agentPrompt`; the gate as `gatePlugin`, `gateTool`, `gateArgs`; the waiver as `gateWaived`. Use `schedule-update` with `agentDispatch` to modify or `agentDispatch: null` to clear. On WhatsApp, a destination bound as an account-manager scopes the spawned session to its sub-account — unless that same phone is also on the house `adminPhones` list, in which case it scopes to the channel account, because the dispatch rides the house socket and so arrives from the house number. On Telegram the session runs on the house account.
 
 A WhatsApp `agentDispatch` destination may therefore be an account manager, not only an admin phone — this is the supported way to send a manager a proactive or scheduled WhatsApp message. The reply is delivered over the house's paired line regardless of which sub-account the session is scoped to; socket ownership never restricts which number the dispatch can reach.
 

package/payload/platform/plugins/scheduling/mcp/dist/index.js

@@ -13,9 +13,11 @@ import { scheduleCancel } from "./tools/schedule-cancel.js";
 import { scheduleExportIcs } from "./tools/schedule-export-ics.js";
 import { scheduleImportIcs } from "./tools/schedule-import-ics.js";
 import { scheduleArchiveIcs } from "./tools/schedule-archive-ics.js";
-import { syncConnectorBusy } from "./tools/schedule-connector-busy-sync.js";
+import { resolveAndSyncConnectorBusy, syncConnectorBusy, } from "./tools/schedule-connector-busy-sync.js";
+import { resolveConnector, spawnProviderCall } from "./lib/connector-freebusy.js";
 import { closeDriver, getUserTimezone, getSession } from "./lib/neo4j.js";
 import { formatCombined } from "./lib/time-format.js";
+import { join, resolve } from "node:path";
 // Cast to `any` to avoid TS2589. TypeScript hits its 50-level instantiation
 // limit when accumulating typed tool signatures on a generic McpServer.
 // Individual tool handlers retain full type safety in their own files.
@@ -70,6 +72,9 @@ const gateShape = {
     args: z.record(z.unknown()).optional().describe("Arguments passed to the gate tool verbatim"),
 };
 const GATE_DESCRIPTION = "Precondition: before this routine spawns an agent turn, the dispatcher calls this tool headlessly and reads structuredContent.hasWork. False skips the turn entirely; true dispatches as normal. A gate that errors, times out or returns no boolean dispatches anyway, so a broken gate never silently mutes the routine. Requires a complete agentDispatch and is refused on an action-mode event.";
+// Task 2383 — the declared exception, on the create path only. `schedule-update`
+// takes no waiver: an existing routine keeps what it has until it is edited.
+const GATE_WAIVED_DESCRIPTION = "The declared reason this recurring routine runs a model on every fire with no gate. A daily briefing or a weekly digest composes from scratch each time and has judgement to apply whether or not anything changed; a conditional sweep does not, and belongs behind a gate. Required when a recurring agentDispatch carries no gate — the write is refused without one. Stored on the event and counted by the standing gate-classification check, so every deliberate exception stays readable.";
 // ---------------------------------------------------------------------------
 // schedule-event
 // ---------------------------------------------------------------------------
@@ -98,6 +103,7 @@ eagerTool(server, "schedule-event", "Create a scheduled event or appointment. A
         prompt: z.string().describe("The instruction the agent runs when the event fires"),
     }).optional().describe("Agent-bearing dispatch: when the event fires, spawns or resumes the admin channel session for `destination` and runs `prompt` with full admin tools, delivering the answer back over the channel. Mutually exclusive with `action`. Always records an event, never a meeting."),
     gate: z.object(gateShape).optional().describe(GATE_DESCRIPTION),
+    gateWaived: z.string().optional().describe(GATE_WAIVED_DESCRIPTION),
 }, async (params) => {
     if (!accountId)
         return refuseNoAccount("schedule-event");
@@ -138,6 +144,8 @@ eagerTool(server, "schedule-event", "Create a scheduled event or appointment. A
             parts.push(`agent dispatch: ${params.agentDispatch.channel} → ${params.agentDispatch.destination}`);
         if (params.gate)
             parts.push(`gate: ${params.gate.plugin}/${params.gate.tool}`);
+        if (params.gateWaived)
+            parts.push(`gate waived: ${params.gateWaived}`);
         return { content: [{ type: "text", text: parts.join(", ") }] };
     }
     catch (err) {
@@ -150,24 +158,61 @@ eagerTool(server, "schedule-event", "Create a scheduled event or appointment. A
 // ---------------------------------------------------------------------------
 // schedule-connector-busy-sync (Task 1654)
 // ---------------------------------------------------------------------------
-eagerTool(server, "schedule-connector-busy-sync", "Reflect your calendar connector's busy blocks into your booking page availability. Call this from the recurring connector-sync turn after reading your Google Calendar or Microsoft 365 free/busy: pass connector='google' or 'm365' and busy as the list of {start,end} ISO 8601 busy intervals. If no calendar connector is authorised, pass connector='none' and busy=[] to clear stale blocks. Wholesale-replaces the stored connector-busy set for this account.", {
-    connector: z.enum(["google", "m365", "none"]).describe("Which calendar connector these busy blocks came from, or 'none' if no connector is authorised"),
+eagerTool(server, "schedule-connector-busy-sync", "Reflect your calendar connector's busy blocks into your booking page availability. Call it with NO arguments and it resolves the account's own authorised connector, reads the next 15 days of free/busy itself, and syncs — that is the normal use and needs no reading step from you. Passing connector and busy together is the explicit form: connector='google' or 'm365' with the list of {start,end} ISO 8601 busy intervals, or connector='none' and busy=[] to clear stale blocks. Wholesale-replaces the stored connector-busy set for this account.", {
+    connector: z.enum(["google", "m365", "none"]).optional().describe("Which calendar connector these busy blocks came from, or 'none' if no connector is authorised. Omit together with busy to have the tool resolve the account's own connector."),
     busy: z.array(z.object({
         start: z.string().describe("ISO 8601 busy-block start"),
         end: z.string().describe("ISO 8601 busy-block end"),
-    })).describe("Busy intervals read from the connector. Empty when connector='none'."),
+    })).optional().describe("Busy intervals read from the connector. Empty when connector='none'. Omit to have the tool read the next 15 days itself."),
 }, async (params) => {
     if (!accountId)
         return refuseNoAccount("schedule-connector-busy-sync");
+    // Both halves are refused rather than defaulted, and for the same reason:
+    // either one alone would be silently reinterpreted. A busy list with no
+    // connector would have to guess where the intervals came from, and that tag
+    // is what a later sync compares against. A connector with no busy list would
+    // be discarded in favour of whatever the account actually holds, so a caller
+    // naming the wrong connector would be told nothing and get a different one.
+    if (Boolean(params.busy) !== Boolean(params.connector)) {
+        const passed = params.busy ? "busy" : "connector";
+        const missing = params.busy ? "connector" : "busy";
+        return {
+            content: [{ type: "text", text: `schedule-connector-busy-sync: ${passed} was passed without ${missing}. Pass both, or neither to have the tool resolve and read the account's own connector.` }],
+            isError: true,
+        };
+    }
     const session = getSession();
     try {
-        const r = await syncConnectorBusy(session, accountId, params);
+        let r;
+        if (params.busy && params.connector) {
+            r = await syncConnectorBusy(session, accountId, { connector: params.connector, busy: params.busy });
+        }
+        else {
+            const platformRoot = process.env.PLATFORM_ROOT ?? process.cwd();
+            const accountsDir = resolve(platformRoot, "..", "data/accounts");
+            // Resolved twice — here and inside resolveAndSyncConnectorBusy — because
+            // spawnProviderCall builds the provider environment eagerly and throws
+            // when the brand ships no vendor app. An account with no connector at all
+            // must reach the clean empty sync instead.
+            const { connector } = resolveConnector(join(accountsDir, accountId));
+            r = await resolveAndSyncConnectorBusy(session, accountId, {
+                accountsDir,
+                platformRoot,
+                now: new Date(),
+                call: connector === "none"
+                    ? async () => { throw new Error("no calendar connector is authorised for this account"); }
+                    : spawnProviderCall(platformRoot, accountId, connector),
+            });
+        }
         process.stderr.write(`[calendar-availability] op=cal-sync connector=${r.connector} busyBlocks=${r.busyBlocks} reflected=${r.reflected}\n`);
         return { content: [{ type: "text", text: `Synced ${r.reflected} connector busy block(s) from ${r.connector}.` }] };
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[calendar-availability] op=cal-sync-fail connector=${params.connector} reason=${JSON.stringify(reason)}\n`);
+        // `resolved` rather than `undefined` when the caller passed no connector:
+        // the connector on this line is what the caller supplied, and the resolved
+        // value is already on the `[connector-busy-sync] op=` lines above.
+        process.stderr.write(`[calendar-availability] op=cal-sync-fail connector=${params.connector ?? "resolved"} reason=${JSON.stringify(reason)}\n`);
         return { content: [{ type: "text", text: `Connector busy sync failed: ${reason}` }], isError: true };
     }
     finally {