@catalyst-cloud/cli 0.16.31 → 0.16.32

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.16.32
+
+The 15-minute release check now moves a self-hosted machine to a newer runner release at set times of day, 03:00, 11:00, 16:00 and 22:00 in the machine's time zone, instead of whenever a release is approved. `catalyst update policy windows 06:00,18:00 --time-zone America/Chicago` sets your own times, `catalyst update policy windows default` goes back to these, and `catalyst update policy` lists them. `catalyst runner update` and `catalyst update` still apply a release at once. A machine that an earlier CLI moved onto the current release now records what it needs to take the next release in place, so it no longer waits for one more release first.
+
 ## 0.16.31
 
 New: `catalyst update` is one release check for everything Catalyst installed on this machine. `catalyst update --check` lists each component (the runner images, the CLI, the Cloud and Dev skills, the Claude plugin form of the Cloud skills, the local replica and each registered project's SDK) with its installed and approved versions, and `catalyst update` moves them to the approved release. `catalyst update policy <component> on|off` holds or releases one component. `catalyst runner update --check` and `catalyst runner auto-update on|off` still work and now cover the same components. The CLI updates itself without breaking the command that is running. If that update fails, the report says so, keeps you on the version you have, and tries again at the next release check. Copied skills never move back to an older version. A running local replica comes back on the new CLI with its synced data. When it cannot, `catalyst replica status` says why and where the data is kept. The Claude plugin moves only to the approved version, and after a move the report tells you to run `/reload-plugins` or restart Claude Code. `catalyst update --json` has a new field, `approvedSkills`, naming the version, repository and full commit each skills pack was approved at. It is `null` when no approval applies.

package/README.md

@@ -305,7 +305,7 @@ The skill files themselves are written by whichever install command you ran, in
 
 ## Updating
 
-`catalyst update --check` lists each installed component beside the version your workspace approved, says which one is behind and why, and changes nothing. Add `--project <absolute path>` to include a project's SDK; the report gives the one command that moves it, `catalyst update sdk --project <path>`. A project's files change only when you run that command, or after you turn its SDK updates on with `catalyst update policy sdk on --project <path>`. `catalyst update` moves the runner images, the CLI, the Cloud skills (copied on this machine or installed as the Claude plugin), and a running local replica to the approved versions. The new CLI is installed beside the old one, and your `catalyst` command runs it from then on, at the same path. A running replica restarts on it and keeps its synced data; a stopped one stays stopped. The Claude plugin moves through Claude Code, and only when its marketplace serves the approved version; run `/reload-plugins` or restart Claude Code afterwards. When the release check cannot find the `claude` command, it changes nothing and prints the one command that moves the plugin. The development skills are not on the approved release yet: the report lists their version as unknown and gives no command for them, so update them the way you installed them. On a machine whose runner checks for releases every 15 minutes (`catalyst runner auto-update on`), that check moves the same components by itself. Otherwise they move when you run `catalyst update`. Each component is on by default; turn one off with `catalyst update policy <component> off` (for example `cli`), and `catalyst update policy` lists every setting. If you turned the installer's daily update off, the CLI and both skills packs start held, and `catalyst update policy cli on` turns the CLI back on. Add `--json` for a machine-readable report.
+`catalyst update --check` lists each installed component beside the version your workspace approved, says which one is behind and why, and changes nothing. Add `--project <absolute path>` to include a project's SDK; the report gives the one command that moves it, `catalyst update sdk --project <path>`. A project's files change only when you run that command, or after you turn its SDK updates on with `catalyst update policy sdk on --project <path>`. `catalyst update` moves the runner images, the CLI, the Cloud skills (copied on this machine or installed as the Claude plugin), and a running local replica to the approved versions. The new CLI is installed beside the old one, and your `catalyst` command runs it from then on, at the same path. A running replica restarts on it and keeps its synced data; a stopped one stays stopped. The Claude plugin moves through Claude Code, and only when its marketplace serves the approved version; run `/reload-plugins` or restart Claude Code afterwards. When the release check cannot find the `claude` command, it changes nothing and prints the one command that moves the plugin. The development skills are not on the approved release yet: the report lists their version as unknown and gives no command for them, so update them the way you installed them. On a machine whose runner checks for releases every 15 minutes (`catalyst runner auto-update on`), that check moves the same components by itself. Otherwise they move when you run `catalyst update`. That check moves the runner images to a newer release only at set times of day, 03:00, 11:00, 16:00 and 22:00 in the machine's time zone, so a busy machine is not restarted every time a release is approved. `catalyst update policy windows 06:00,18:00 --time-zone America/Chicago` sets your own times, `catalyst update policy windows default` goes back to these, and `catalyst runner update` or `catalyst update` applies a waiting release at once. Each component is on by default; turn one off with `catalyst update policy <component> off` (for example `cli`), and `catalyst update policy` lists every setting. If you turned the installer's daily update off, the CLI and both skills packs start held, and `catalyst update policy cli on` turns the CLI back on. Add `--json` for a machine-readable report.
 
 A CLI older than `catalyst update` cannot move itself: install it once with `npm install -g @catalyst-cloud/cli@latest && catalyst login`. The re-login rewrites the CLI path the skills spawn, so they stop running the old bundle. To run one command against the latest publish without installing, use `npx -p @catalyst-cloud/cli@latest catalyst login`. The next `catalyst` run prints a one-line notice:
 

package/dist/args.js

@@ -33,6 +33,7 @@ export const FLAG_TABLES = {
         check: { value: false, help: "read the approved release and list every component against it, without changing anything" },
         project: { value: true, help: "also check this project's SDK (an absolute path); with policy sdk, the project the setting is for" },
         dir: { value: true, help: "the runner directory (default: the one setup created)" },
+        "time-zone": { value: true, help: "policy windows: the time zone the window times are in (default: this machine's)" },
     },
     login: {
         "start-replica": {
@@ -580,7 +581,7 @@ export const FLAG_TABLES = {
 export const VERB_USAGE = {
     hosts: "hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name> [--json]",
     runner: "runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off] [--json]",
-    update: "update [--check] [--project <absolute path>] [--dir <runner directory>] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path> [--json]   (components: runner, supervisor, watchdog, cli, skills-cloud, skills-dev, replica)",
+    update: "update [--check] [--project <absolute path>] [--dir <runner directory>] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path> | update policy windows <HH:MM,...>|default [--time-zone <zone>] [--json]   (components: runner, supervisor, watchdog, cli, skills-cloud, skills-dev, replica)",
     setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
     onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--remove-local-data] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--remove-local-data] [--json]",

package/dist/capabilities.js

@@ -10,7 +10,7 @@ export const CAPABILITIES = [
     { verb: "runner update|auto-update", does: "move this machine's self-hosted runner to the release Catalyst approved, and check for one every 15 minutes", needs: "member", routes: [], since: "0.16.16" },
     { verb: "update", does: "list every installed component against the release Catalyst approved, move the runner images to it, and name the command for the rest", needs: "member", routes: [], since: "0.16.31" },
     { verb: "update sdk", does: "move one project's Catalyst SDK to the approved versions with its own package manager, when the person asks", needs: "member", routes: [], since: "0.16.31" },
-    { verb: "update policy", does: "turn automatic updates off or on for one installed component, or set a project's SDK to notify only", needs: "member", routes: [], since: "0.16.31" },
+    { verb: "update policy", does: "turn automatic updates off or on for one installed component, set a project's SDK to notify only, or set the times of day runner releases apply", needs: "member", routes: [], since: "0.16.31" },
     { verb: "runner status|stop|start", does: "stop this machine's self-hosted runner taking work, or start it again with the same registration", needs: "member", routes: [], since: "0.16.27" },
     { verb: "runner uninstall", does: "remove this machine's self-hosted runner and revoke its registration and runner key", needs: "admin", routes: [], since: "0.16.27" },
     // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh

package/dist/cli.js

@@ -92,7 +92,7 @@ export function usageText() {
         "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
         "  catalyst runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts]   (this machine's self-hosted runner)",
         "  catalyst runner update [--check] | runner auto-update [status|on|off]   (move this machine's runner to the approved release)",
-        "  catalyst update [--check] [--project <path>] | update policy [<component> on|off]   (every installed component against the approved release)",
+        "  catalyst update [--check] [--project <path>] | update policy [<component> on|off] | update policy windows <HH:MM,...>|default   (every installed component against the approved release)",
         "  catalyst mcp add|list|remove (vault references only) | mcp status <name>   (a server's state, grants and last 50 tool calls)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",

package/dist/runner-command.js

@@ -7,6 +7,7 @@ import { dockerFleetUpdateEngine, runFleetUpdate } from "./runner-update-fleet.j
 import { runUpdate, sharedReleaseRead, updateReportJson, updateReportLines } from "./update.js";
 import { effectivePolicy, readUpdatePolicy, setComponentPolicy } from "./update-policy.js";
 import { resolveClaude } from "./update-plugin.js";
+import { defaultWindows, windowBounds } from "./update-windows.js";
 import { cmdRunnerLifecycle, RUNNER_LIFECYCLE_ACTIONS } from "./runner.js";
 const USAGE = "catalyst runner [status] | stop | start | uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off]";
 const UPDATE_FLAGS = ["check", "auto", "dir", "fleet"];
@@ -110,6 +111,8 @@ export async function cmdRunner(args, ctx, deps = {}) {
         };
         // An owner's image hold stops this command's image work too, including the schedule's (CTC-6708).
         const hold = check ? null : imageHold(ctx);
+        // The schedule's run takes a newer release only in an update window; an owner's run applies at
+        // once (CTC-6709, update-windows.ts).
         if (hold !== null) {
             const retained = { outcome: "retained", detail: hold, generation: readReleaseState(dir()).generation, exitCode: hold === "owner_setting" ? 0 : 1 };
             // Unreadable settings move nothing; a hold leaves the other components to the release check.
@@ -117,7 +120,7 @@ export async function cmdRunner(args, ctx, deps = {}) {
         }
         const result = fleet
             ? await runFleetUpdate(deps.fleetEngine ?? dockerFleetUpdateEngine({ env: ctx.env }), { dir: dir(), check })
-            : await runRunnerUpdate(engine, { dir: dir(), check });
+            : await runRunnerUpdate(engine, { dir: dir(), check, ...(auto && !check ? { window: windowBounds(ctx.now().getTime(), readUpdatePolicy(ctx.home).windows ?? defaultWindows()) } : {}) });
         // `runner update --check` also lists every installed component against the approved release, as
         // `catalyst update --check` does. The image fields stay where scripts already read them.
         if (check && !fleet && !auto) {

package/dist/runner-update.js

@@ -119,7 +119,7 @@ export function decideRelease(appliedGeneration, read) {
     return { action: "update", release };
 }
 export function readReleaseState(dir) {
-    const empty = { version: 1, generation: null, releaseId: null, appliedAtMs: null, previous: null, journal: null, pendingRemoval: [], last: null };
+    const empty = { version: 1, generation: null, releaseId: null, appliedAtMs: null, previous: null, journal: null, pendingRemoval: [], windowSettledMs: null, last: null };
     try {
         const parsed = JSON.parse(readFileSync(join(dir, RELEASE_STATE_FILE), "utf8"));
         if (!isRecord(parsed) || parsed.version !== 1)
@@ -136,6 +136,7 @@ export function readReleaseState(dir) {
             pendingRemoval: Array.isArray(parsed.pendingRemoval)
                 ? parsed.pendingRemoval.filter((ref) => typeof ref === "string").slice(0, PENDING_REMOVAL_KEPT)
                 : [],
+            windowSettledMs: posInt(parsed.windowSettledMs) ? parsed.windowSettledMs : null,
             last: isRecord(parsed.last) ? parsed.last : null,
         };
     }
@@ -172,6 +173,9 @@ export function rewriteEnvText(text, values) {
     }
     return lines.join("\n");
 }
+/** Outcomes that settle a window: nothing was pending, or the machine restarted onto (or tried) a
+ *  release. A busy deferral or a passing refusal leaves the window open for the next check. */
+const SETTLES_WINDOW = new Set(["current", "recorded", "updated", "rolled_back", "failed"]);
 /** One serialized update run. A second concurrent run returns `retained` with `update_running`. */
 export async function runRunnerUpdate(engine, options) {
     const { dir } = options;
@@ -188,7 +192,8 @@ export async function runRunnerUpdate(engine, options) {
         const result = await update(engine, options, now);
         if (!options.check) {
             const state = readReleaseState(dir);
-            writeReleaseState(dir, { ...state, last: { atMs: now(), outcome: result.outcome, detail: result.detail, generation: result.generation } });
+            const windowSettledMs = options.window && SETTLES_WINDOW.has(result.outcome) ? options.window.lastOpenedMs : state.windowSettledMs;
+            writeReleaseState(dir, { ...state, windowSettledMs, last: { atMs: now(), outcome: result.outcome, detail: result.detail, generation: result.generation } });
         }
         return result;
     }
@@ -232,6 +237,13 @@ async function update(engine, options, now) {
             ? done("current", "not_newer")
             : done("retained", decision.reason, { exitCode: decision.reason === "credential_refused" || decision.reason === "no_credential" ? 1 : 0 });
     const { release } = decision;
+    const tagged = { releaseId: release.releaseId };
+    // A newer release on the schedule waits for a window no run has settled. A machine that has
+    // settled none yet (its first run on this CLI) takes it now, and drift on the applied generation
+    // is put right at once, as before.
+    const { window } = options;
+    if (window && !options.check && decision.action === "update" && state.windowSettledMs !== null && window.lastOpenedMs <= state.windowSettledMs)
+        return done("waiting_window", `next_window:${new Date(window.nextOpensMs).toISOString()}`, tagged);
     const target = Object.fromEntries(RELEASE_COMPONENTS.map((c) => [c, release.images[c].reference]));
     const envText = readFileSync(envPath, "utf8");
     const env = readEnvFile(envPath) ?? {};
@@ -241,10 +253,15 @@ async function update(engine, options, now) {
     // (no log read). A match is current; any drift is moved back below like any other update.
     if (decision.action === "verify" && changed.length === 0) {
         const live = await engine.services(dir, signal);
-        if (live?.supervisor?.running && live.supervisor.image === target.supervisor && live.watchdog?.image === target.watchdog)
+        if (live?.supervisor?.running && live.supervisor.image === target.supervisor && live.watchdog?.image === target.watchdog) {
+            // A CLI before 0.16.31 applied this release without recording its journal format. Its
+            // supervisor is the one running, so record the format now: the next release can then go in
+            // place instead of waiting for one more applied generation.
+            if (!options.check && state.journal === null && release.journalFormat !== null)
+                writeReleaseState(dir, { ...state, journal: { format: release.journalFormat, supervisor: target.supervisor } });
             return done("current", "not_newer");
+        }
     }
-    const tagged = { releaseId: release.releaseId };
     const record = (outcome, detail, previous, unremoved = []) => {
         const journal = release.journalFormat === null ? null : { format: release.journalFormat, supervisor: target.supervisor };
         const pendingRemoval = [...new Set([...state.pendingRemoval, ...unremoved])].slice(-PENDING_REMOVAL_KEPT);
@@ -550,6 +567,7 @@ const OUTCOME_TEXT = {
     updated: "The runner moved to the approved release.",
     planned: "Checked the approved release; nothing was changed.",
     deferred_busy: "A phase is running here, so the update waits for the next check.",
+    waiting_window: "An approved release waits for this machine's next update window.",
     retained: "Kept the current images.",
     rolled_back: "The new supervisor did not become ready, so the previous images were restored.",
     failed: "The update could not finish. Look at the runner with docker compose ps.",

package/dist/update-command.js

@@ -10,8 +10,9 @@ import { UsageError } from "./errors.js";
 import { dockerRunnerUpdateEngine, runnerDir } from "./runner-update.js";
 import { policyLines, readEffectivePolicy, runUpdate, updateReportJson, updateReportLines } from "./update.js";
 import { applySdkUpdate } from "./update-sdk.js";
-import { canonicalProject, effectivePolicy, isUpdateComponent, readUpdatePolicy, setComponentPolicy, setProjectSdkPolicy, UPDATE_COMPONENTS, } from "./update-policy.js";
-const USAGE = "catalyst update [--check] [--project <absolute path>] [--dir <runner directory>] [--json] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path>";
+import { DEFAULT_WINDOW_TIMES, isTimeZone, normalizeWindowTimes } from "./update-windows.js";
+import { canonicalProject, effectivePolicy, isUpdateComponent, readUpdatePolicy, setComponentPolicy, setProjectSdkPolicy, setWindowPolicy, UPDATE_COMPONENTS, } from "./update-policy.js";
+const USAGE = "catalyst update [--check] [--project <absolute path>] [--dir <runner directory>] [--json] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path> | update policy windows <HH:MM,...>|default [--time-zone <zone>]";
 /** How each component reads in a sentence. */
 const SENTENCE_NAMES = {
     runner: "runner",
@@ -40,12 +41,17 @@ function cmdPolicy(parts, args, ctx) {
             ctx.stdout(JSON.stringify({
                 components: UPDATE_COMPONENTS.map((id) => ({ id, ...effectivePolicy(policy, id) })),
                 projects: policy.projects.map((p) => ({ path: p.path, sdk: p.sdk, source: p.source })),
+                windows: { times: policy.windows?.times ?? [...DEFAULT_WINDOW_TIMES], timeZone: policy.windows?.timeZone ?? null, source: policy.windows ? "owner" : "default" },
             }));
         else
             for (const line of policyLines(policy))
                 ctx.stdout(line);
         return 0;
     }
+    if (parts[1] === "windows")
+        return cmdWindows(parts, args, ctx);
+    if (args.flags["time-zone"] !== undefined)
+        throw new UsageError("--time-zone goes with update policy windows");
     const [, name, value] = parts;
     if (parts.length !== 3 || (value !== "on" && value !== "off") || name === undefined)
         throw new UsageError(USAGE);
@@ -74,6 +80,35 @@ function cmdPolicy(parts, args, ctx) {
         ctx.stdout(`Automatic ${SENTENCE_NAMES[name]} updates are ${value}. Other components keep their settings.`);
     return 0;
 }
+/** `update policy windows 03:00,11:00|default [--time-zone <zone>]`: when the schedule may take a
+ *  newer runner release. `default` goes back to the four default times in the machine's zone. */
+function cmdWindows(parts, args, ctx) {
+    const value = parts[2];
+    if (parts.length !== 3 || value === undefined)
+        throw new UsageError(USAGE);
+    const zone = flagString(args, "time-zone");
+    if (value === "default") {
+        if (zone !== undefined)
+            throw new UsageError("update policy windows default uses this machine's time zone; leave out --time-zone");
+        setWindowPolicy(ctx.home, null);
+    }
+    else {
+        const times = normalizeWindowTimes(value.split(","));
+        if (times === null)
+            throw new UsageError("update windows are 24-hour times separated by commas, for example 03:00,11:00,16:00,22:00");
+        if (zone !== undefined && !isTimeZone(zone))
+            throw new UsageError(`unknown time zone: ${zone}. Use a name such as America/Chicago`);
+        setWindowPolicy(ctx.home, { times, timeZone: zone ?? null });
+    }
+    const saved = readUpdatePolicy(ctx.home).windows;
+    const times = saved?.times ?? [...DEFAULT_WINDOW_TIMES];
+    const timeZone = saved?.timeZone ?? null;
+    if (args.json)
+        ctx.stdout(JSON.stringify({ windows: { times, timeZone, source: saved ? "owner" : "default" } }));
+    else
+        ctx.stdout(`Runner releases now apply at ${times.join(", ")} (${timeZone ?? "this machine's time zone"}). catalyst runner update still applies one at once.`);
+    return 0;
+}
 async function cmdSdk(parts, args, ctx, deps) {
     if (parts.length !== 1)
         throw new UsageError(USAGE);

package/dist/update-policy.js

@@ -15,6 +15,7 @@ import { isAbsolute, join } from "node:path";
 import { configDirFor } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { isRecord, writePrivateAtomic } from "./runner-update.js";
+import { isTimeZone, normalizeWindowTimes } from "./update-windows.js";
 export const UPDATE_POLICY_FILE = "updates.json";
 const LOCK_STALE_MS = 30_000;
 const LOCK_WAIT_MS = 5_000;
@@ -77,6 +78,15 @@ function parsePolicy(input) {
             policy.projects.push({ path: value.path, sdk: value.sdk, source: value.source, dev: value.dev, ino: value.ino });
         }
     }
+    if (input.windows !== undefined) {
+        if (!isRecord(input.windows) || !Array.isArray(input.windows.times))
+            return null;
+        const times = input.windows.times.every((t) => typeof t === "string") ? normalizeWindowTimes(input.windows.times) : null;
+        const zone = input.windows.timeZone;
+        if (times === null || !(zone === null || (typeof zone === "string" && isTimeZone(zone))))
+            return null;
+        policy.windows = { times, timeZone: zone };
+    }
     return policy;
 }
 /** The components an installer's daily update kept current: the CLI and both skills packs. */
@@ -192,3 +202,12 @@ export function setProjectSdkPolicy(home, path, sdk) {
     });
     return saved ?? { ...project, sdk, source: "owner" };
 }
+/** Save the owner's update windows, or go back to the defaults with null. */
+export function setWindowPolicy(home, windows) {
+    return updateUpdatePolicy(home, (policy) => {
+        if (windows === null)
+            delete policy.windows;
+        else
+            policy.windows = windows;
+    });
+}

package/dist/update-windows.js

@@ -0,0 +1,81 @@
+// update-windows.ts — the set times of day a self-hosted machine takes a new release (CTC-6709).
+// The 15-minute schedule checks often so an owner sees the approved release quickly, but a busy
+// machine restarting its supervisor every time a release lands would interrupt its owner's day as
+// often as releases ship. So the schedule applies a newer release only once a window has opened
+// since the last window a run settled, and an owner's own `catalyst runner update` applies at once.
+// Windows are wall-clock times in the machine's time zone, or the zone its owner saved.
+/** Four windows a day, spread so a release approved at any time waits at most about eight hours. */
+export const DEFAULT_WINDOW_TIMES = ["03:00", "11:00", "16:00", "22:00"];
+const TIME = /^([01][0-9]|2[0-3]):([0-5][0-9])$/;
+export function defaultWindows() {
+    return { times: [...DEFAULT_WINDOW_TIMES], timeZone: null };
+}
+export function isWindowTime(value) {
+    return TIME.test(value);
+}
+/** Whether this runtime knows the zone. `Intl` throws a RangeError for one it does not. */
+export function isTimeZone(value) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+        return value.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function machineTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+/** Sorted, distinct `HH:MM` times, or null when any entry is not one or there are none. */
+export function normalizeWindowTimes(values) {
+    if (values.length === 0 || values.length > 24 || !values.every(isWindowTime))
+        return null;
+    return [...new Set(values)].sort();
+}
+/** The zone's wall clock at an instant, as the parts a window time is compared with. */
+function wallClock(ms, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+    }).formatToParts(new Date(ms));
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+    return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour"), minute: get("minute") };
+}
+/** The zone's offset from UTC at an instant, in milliseconds, to the minute. */
+function offsetMs(ms, timeZone) {
+    const w = wallClock(ms, timeZone);
+    return Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute) - Math.floor(ms / 60_000) * 60_000;
+}
+/** The instant a wall-clock time falls on in the zone. A time a clock change skips or repeats lands within an hour of it. */
+function instantOf(year, month, day, hour, minute, timeZone) {
+    const asUtc = Date.UTC(year, month - 1, day, hour, minute);
+    const first = asUtc - offsetMs(asUtc, timeZone);
+    return asUtc - offsetMs(first, timeZone);
+}
+/** The window before and after `nowMs`. */
+export function windowBounds(nowMs, windows) {
+    const timeZone = windows.timeZone ?? machineTimeZone();
+    const times = normalizeWindowTimes(windows.times) ?? [...DEFAULT_WINDOW_TIMES];
+    const today = wallClock(nowMs, timeZone);
+    const candidates = [];
+    // Two calendar days either side of today's date in the zone. Stepping by date, not by 24 hours,
+    // keeps a 23- or 25-hour day around a clock change from skipping a date or reading one twice.
+    for (let shift = -2; shift <= 2; shift++) {
+        const date = new Date(Date.UTC(today.year, today.month - 1, today.day + shift));
+        for (const time of times) {
+            const [hour, minute] = time.split(":").map(Number);
+            candidates.push(instantOf(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(), hour, minute, timeZone));
+        }
+    }
+    candidates.sort((a, b) => a - b);
+    const lastOpenedMs = candidates.filter((ms) => ms <= nowMs).pop();
+    const nextOpensMs = candidates.find((ms) => ms > nowMs);
+    if (lastOpenedMs === undefined || nextOpensMs === undefined)
+        throw new Error(`no update window around ${new Date(nowMs).toISOString()} in ${timeZone}`);
+    return { lastOpenedMs, nextOpensMs, timeZone };
+}

package/dist/update.js

@@ -27,6 +27,7 @@ import { applyCloudPluginUpdate, CLOUD_PLUGIN_COMMAND } from "./update-plugin.js
 import { onboardStatePath, readOnboardJournal } from "./onboard.js";
 import { effectivePolicy, projectIdentityHolds, readUpdatePolicy, UPDATE_COMPONENTS, withMigratedHolds, } from "./update-policy.js";
 import { applySdkUpdate, inspectSdkProject } from "./update-sdk.js";
+import { DEFAULT_WINDOW_TIMES } from "./update-windows.js";
 import { decideRelease, isRecord, parseDesiredRelease, RELEASE_COMPONENTS, runRunnerUpdate, } from "./runner-update.js";
 export const COMPONENT_LABELS = {
     runner: "Runner",
@@ -248,7 +249,7 @@ function applyImageResult(rows, result) {
             row.installed = row.approved;
             row.installedReference = row.approvedReference ?? row.installedReference ?? null;
         }
-        else if (result.outcome === "deferred_busy" || result.outcome === "retained") {
+        else if (result.outcome === "deferred_busy" || result.outcome === "waiting_window" || result.outcome === "retained") {
             if (row.status === "update_available") {
                 row.status = "pending";
                 row.reason = result.detail;
@@ -582,5 +583,7 @@ export function policyLines(policy) {
         lines.push("SDK projects: none registered");
     for (const project of policy.projects)
         lines.push(`${cell(`SDK ${project.path}`, 19)}${cell(project.sdk === "auto" ? "on" : "off", 5)}(${project.source}${project.sdk === "notify" ? ", notify only" : ""})`);
+    const windows = policy.windows;
+    lines.push(`Runner releases apply at ${(windows?.times ?? DEFAULT_WINDOW_TIMES).join(", ")} (${windows?.timeZone ?? "this machine's time zone"}; ${windows ? "owner" : "default"})`);
     return lines;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.31",
+  "version": "0.16.32",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.32 — written in this repository for customer accounts -->
 
 # What's happening