@rubytech/create-maxy-code 0.1.551 → 0.1.553

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/whats-new/SKILL.md

@@ -9,6 +9,17 @@ 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.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.
+- When the device runs short on memory, the largest chat is now stopped before the system starts swapping, rather than after everything has slowed down.
+
 ## 2026-08-02 (0.1.551)
 
 - You can now run as many Telegram bots as you like, each paired to its own agent, with its own access list, secret and conversations kept apart. Existing setups are converted automatically, the sidebar splits by bot, and a standing check reports each one.

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

@@ -39,6 +39,10 @@ tools:
     publicAllowlist: false
     adminAllowlist: false
     riskClass: write_local
+  - name: scheduling-gate
+    publicAllowlist: false
+    adminAllowlist: true
+    riskClass: read
   - name: schedule-connector-busy-sync
     publicAllowlist: false
     adminAllowlist: true
@@ -101,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:
@@ -264,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

@@ -3,6 +3,7 @@ import { eagerTool } from "../../../../lib/mcp-eager/dist/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { scheduleEvent } from "./tools/schedule-event.js";
+import { runSchedulingGate } from "./tools/scheduling-gate.js";
 import { scheduleList } from "./tools/schedule-list.js";
 import { scheduleGet } from "./tools/schedule-get.js";
 import { scheduleRuns } from "./tools/schedule-runs.js";
@@ -12,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.
@@ -61,6 +64,17 @@ const eventStatusSchema = z
     .enum(EVENT_STATUSES)
     .optional()
     .describe("Event status. 'suspended' pauses a routine: it stops firing and stays paused until it is set back to 'scheduled', which resumes it at its next natural occurrence. 'cancelled' is not set here — use schedule-cancel, which ends the series permanently.");
+// Task 2378 — the precondition, shared by both write tools so the create path
+// and the edit path cannot describe it differently to the agent.
+const gateShape = {
+    plugin: z.string().describe("Plugin exposing the gate tool (e.g. 'scheduling')"),
+    tool: z.string().describe("MCP tool to call before the routine fires. It must return structuredContent {hasWork:boolean}."),
+    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
 // ---------------------------------------------------------------------------
@@ -88,6 +102,8 @@ eagerTool(server, "schedule-event", "Create a scheduled event or appointment. A
         destination: z.string().describe("E.164 phone (WhatsApp) or Telegram chat id — must already be a registered admin/account-manager on that channel"),
         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");
@@ -126,6 +142,10 @@ eagerTool(server, "schedule-event", "Create a scheduled event or appointment. A
             parts.push(`action: ${params.action.plugin}/${params.action.tool}`);
         if (params.agentDispatch)
             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) {
@@ -138,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 {
@@ -325,6 +382,7 @@ eagerTool(server, "schedule-update", "Update an event's properties or append a n
         destination: z.string().describe("E.164 phone (WhatsApp) or Telegram chat id — must already be a registered admin/account-manager on that channel"),
         prompt: z.string().describe("The instruction the agent runs when the event fires"),
     }).nullable().optional().describe("Set/replace the agent-bearing dispatch, or pass null to clear it. Mutually exclusive with action."),
+    gate: z.object(gateShape).nullable().optional().describe(`${GATE_DESCRIPTION} Pass null to clear it.`),
 }, async (params) => {
     if (!accountId)
         return refuseNoAccount("schedule-update");
@@ -346,6 +404,55 @@ eagerTool(server, "schedule-update", "Update an event's properties or append a n
     }
 });
 // ---------------------------------------------------------------------------
+// scheduling-gate (Task 2378)
+// ---------------------------------------------------------------------------
+eagerTool(server, "scheduling-gate", "Precondition check for a scheduled routine: answers whether any of the named sources has new work, without running a turn. The dispatcher calls this headlessly before firing a gated routine and reads structuredContent.hasWork. Call it yourself with commit=true as the LAST step of a successful routine run, with the same eventId and checks, to advance the watermarks past what you just handled. Never call commit=true on a run that failed or that you did not finish — the work would be marked consumed and the next fire would skip it.", {
+    eventId: z.string().describe("The gated routine's event ID. Names the watermark file, so it must match the binding."),
+    checks: z.array(z.record(z.unknown())).describe("Checks to run. mail {type,mailbox,folder?,subjectPrefixes?} · d1 {type,database,sql} · whatsapp {type,scope:'inbound'|'status'} · calendar {type,connector}. hasWork is true when ANY check is true."),
+    commit: z.boolean().optional().describe("Advance every watermark named in checks to what the sources hold now. Only the routine's own turn sets this, at the end of a successful run."),
+}, async (params) => {
+    if (!accountId)
+        return refuseNoAccount("scheduling-gate");
+    const platformRoot = process.env.PLATFORM_ROOT;
+    if (!platformRoot) {
+        // Refused rather than defaulted: a guessed root would put the watermark
+        // file somewhere the next call would not look, and the routine would
+        // report work for ever.
+        return {
+            content: [{ type: "text", text: "scheduling-gate cannot execute: PLATFORM_ROOT is not set." }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await runSchedulingGate({ eventId: params.eventId, checks: params.checks, commit: params.commit }, accountId, platformRoot);
+        // structuredContent is what the dispatcher reads; the text is for a human
+        // or an agent reading the transcript and is never parsed for control flow.
+        // No outputSchema is declared: the MCP server validates structuredContent
+        // only when a tool has one, so this passes to the wire untouched, and
+        // declaring one would mean changing the shared eagerTool signature.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.advanced
+                        ? `hasWork=${result.hasWork} reasons=[${result.reasons.join(", ")}] advanced=[${result.advanced.join(", ")}]`
+                        : `hasWork=${result.hasWork} reasons=[${result.reasons.join(", ")}]`,
+                },
+            ],
+            structuredContent: result,
+        };
+    }
+    catch (err) {
+        // A throw here reaches the dispatcher as an unreadable gate, which fails
+        // OPEN and dispatches. That is the safe direction and is why this does not
+        // try to synthesise a hasWork value it did not measure.
+        return {
+            content: [{ type: "text", text: `Gate check failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
 // schedule-cancel
 // ---------------------------------------------------------------------------
 eagerTool(server, "schedule-cancel", "Cancel a scheduled event. For recurring events, this cancels the entire series. Idempotent — cancelling an already-cancelled event is a no-op. Passing a meeting uid deletes that meeting and its attendee links, the same as deleting it on the Calendar page.", {