create_pass_window

Place one dated access window by hand on a time-limited pass plan. Marked manual, so a schedule rebuild keeps it; emits pass.window_scheduled.

Purpose

Add a single window to a pass plan's schedule without touching the rule that generates the rest — a one-off extra session, a make-up date, a special. The window is stored as manual, which is what protects it: when the plan's schedule is rebuilt from its slots, generated windows are pruned and regenerated, manual ones are left alone.

Synchronous — the new window comes back in the get_pass_window row shape, and pass.window_scheduled emits once.

A bare `starts_at` is read in the plan's timezone

An ISO 8601 instant with an offset (2026-10-03T09:00:00+01:00 or Z) is taken as given. One without an offset is read in the plan's own pass timezone, not UTC and not the agent's clock, because that is the time the creator means when they say "ten o'clock". The future check runs in that zone too.

The plan's configured floor and ceiling on window length apply, so duration_minutes outside those bounds is refused rather than clamped.

Required ability

pass-window:create

Input schema

{
  "type": "object",
  "required": ["plan_id", "starts_at", "duration_minutes"],
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "UUID of the pass plan to place the window on."
    },
    "starts_at": {
      "type": "string",
      "description": "ISO 8601 instant the window opens. Without an offset it is read in the plan's own timezone."
    },
    "duration_minutes": {
      "type": "integer",
      "minimum": 1,
      "description": "How long the window runs, in whole minutes."
    }
  }
}

Output shape

{
  "data": {
    "id": "3d5a8c72-b016-4e94-8fa7-61c209d4e738",
    "plan_id": "9b7c2e15-4d63-4f80-a2b1-7e5d0c9f3a46",
    "plan_name": "Saturday session",
    "starts_at": "2026-10-03T09:00:00+00:00",
    "ends_at": "2026-10-03T11:00:00+00:00",
    "timezone": "Europe/London",
    "local_range": "Sat 3 Oct, 10:00–12:00 BST",
    "duration_minutes": 120,
    "status": "scheduled",
    "sellable": true,
    "holders": 0
  }
}

Example prompts

"Add an extra two-hour window to plan 9b7c2e15-4d63-4f80-a2b1-7e5d0c9f3a46 on 3 October at 10am local time."

"Schedule a make-up session next Tuesday at 19:00 for 90 minutes on the Saturday session plan."

"Put a one-off 6pm window on the evening pass for the 24th."

Failure modes

VALIDATION_FAILED — the plan is not of kind pass, starts_at is in the past, duration_minutes is outside the plan's minimum and maximum, or the plan already has a window starting at that instant.
RESOURCE_NOT_FOUND — unknown plan_id, or the plan's project is outside the token's scope.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks pass-window:create.

list_pass_windows — check the existing schedule before adding to it.
cancel_pass_window — the reverse.
get_plan — read the plan's timezone and length bounds.
Pass windows API — the REST equivalent.