@catalyst-cloud/cli 0.16.39 → 0.16.40

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.16.40
+
+`catalyst flow --repo <owner/name> --period 2w --granularity day` prints a repository's open pull request counts by the day, or by the hour with `--granularity hour`. `--json` prints the same buckets the SDK's `flow.series()` returns.
+
+A supervisor fleet can now update itself on a schedule: `catalyst runner auto-update on --fleet --dir <fleet directory>` installs a timer that runs `catalyst runner update --fleet` for that directory, and `catalyst runner auto-update status` shows that it is a fleet schedule and which directory it updates.
+
+After `catalyst runner update --fleet` applies a release, it checks the fleet again 10 minutes later. If the supervisor is not running, or the release was granted no work while three requests for work got no response, it restores the previous release and does not apply that release again until a newer one is approved. An idle fleet with nothing to do keeps the new release. `catalyst runner update --check --fleet` names the last check's result.
+
 ## 0.16.39
 
 `catalyst query pulls` now sends `--state`, `--repo` and `--draft` to Catalyst, so `--state open --all` reads only the workspace's open pull requests instead of paging through every pull request it has ever had. `--state` takes `open`, `closed` or `merged`, and `--draft` takes `draft` or `ready`. Any other value is refused before a request is made. `open` and `closed` leave out merged pull requests, and the repository and state match in any letter case. Against an older Catalyst that ignores these filters, the CLI applies them to the rows it gets back, so the result is the same. A filtered read of the local replica now checks every pull request it holds, so an older pull request linked to a ticket is still found.

package/README.md

@@ -240,6 +240,32 @@ Paused rows show who paused the repository (their email, or the key or operator
 
 `--json` preserves the list response for status and prints the refreshed repository row for a write. An older cloud reports that repository status is not served yet and needs a newer cloud. Agents can use `catalyst capabilities --json` to check route availability against the cached cloud contract.
 
+## Open pull requests over time
+
+Print how many pull requests a repository had open, one row per day or per hour:
+
+```sh
+catalyst flow --repo acme/app --period 2w --granularity day
+catalyst flow --repo acme/app --period 24h --granularity hour --json
+catalyst flow
+```
+
+```text
+$ catalyst flow --repo acme/app --period 2w --granularity day
+2026-10-12  27
+2026-10-13  31
+...
+2026-10-25  24  (now)
+```
+
+Each row is one bucket: its start, then the number of pull requests open at its end, drafts included. Daily rows show the date; hourly rows show the time with its UTC offset. Days start at midnight in your workspace's time zone, as the cloud reports it. The last row ends now and is marked `(now)`. A row reads `unavailable` when your workspace cannot attribute pull requests to that repository.
+
+`--period` is one of `24h`, `2d`, `3d`, `1w`, `2w`, `4w`, `12w` or `26w`, and defaults to two weeks. `--granularity` is `hour` or `day`; left out, the period picks the width: one, two or three hours for `24h`, `2d` and `3d`, and a day for the week periods. Hourly rows over a long period can be too much for one answer; the command then exits 2 and suggests daily rows or a shorter period.
+
+Without `--repo`, the command reads this checkout's GitHub origin and uses it when it is a repository of your workspace. Anywhere else it exits 2 and asks for `--repo owner/name`. Any workspace member can read it.
+
+`--json` prints one JSON array with one entry per bucket, exactly as the SDK's `flow.series()` returns them in `series.columns`: `startMs` and `endMs` in epoch milliseconds, `label`, `partial`, and `pr` with `open` and the bucket's other pull request counts.
+
 ## What has to be running
 
 Nothing, by default. After `login`, every read, write, ask and explanation goes to the cloud's origin-fresh API with the config file and the cached contract on disk. Two optional processes exist for people who want them:

package/dist/agent-repoint.js

@@ -13,14 +13,13 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compareVersions, exactVersion } from "./approved-release.js";
 import { LEGACY_PACKAGE_NAME, readManifest } from "./config.js";
-import { AUTO_UPDATE_LABEL, custodyNode, defaultRun, enableAutoUpdate, launchAgentPath, scheduledPath, systemdUnitPaths, writeFileAtomic, } from "./runner-auto-update.js";
+import { AUTO_UPDATE_LABEL, custodyNode, defaultRun, enableAutoUpdate, launchAgentPath, scheduledPath, systemdUnitPaths, unitWords, unxml, writeFileAtomic, } from "./runner-auto-update.js";
 import { CLAUDE_PATH_ENV, resolveClaude } from "./update-plugin.js";
 /** Long enough for an in-place update (under a minute on a Mac measured 2026-10-24), well inside the
  *  installer's 600-second budget for the whole npm install. */
 export const BUSY_WAIT_MS = 240_000;
 const BUSY_POLL_MS = 5_000;
 const blockingSleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-const unxml = (value) => value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&amp;/g, "&");
 /** The agent's command, from a plist this CLI wrote (launchAgentPlist). Anything else is unrecognized. */
 function plistProgram(text) {
     const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text)?.[1];
@@ -33,10 +32,6 @@ function plistProgram(text) {
     };
     return programOf(args, env("PATH"), env(CLAUDE_PATH_ENV));
 }
-/** systemd's quoted words, as systemdUnits writes them. */
-function unitWords(line) {
-    return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? "").replace(/\\(.)/g, "$1").replace(/%%/g, "%"));
-}
 function unitProgram(text) {
     const lines = text.split("\n");
     const exec = lines.find((l) => l.startsWith("ExecStart="));

package/dist/args.js

@@ -25,7 +25,8 @@ export const FLAG_TABLES = {
         check: { value: false, help: "read the approved release and say what would change, without changing it" },
         auto: { value: false, help: "one-line output for the scheduled run" },
         dir: { value: true, help: "the runner directory (default: the one setup created)" },
-        fleet: { value: false, help: "update a multi-team supervisor fleet's compose.json in --dir" },
+        fleet: { value: false, help: "update a multi-team supervisor fleet's compose.json in --dir (with auto-update on: schedule that update)" },
+        "post-roll-check": { value: false, help: "with --fleet and --dir: the check a fleet update arms for 10 minutes after it applies (run by that timer)" },
         yes: { value: false, help: "uninstall: confirm without a terminal" },
         "delete-checkouts": { value: false, help: "uninstall: also delete the repository and thoughts checkouts" },
     },
@@ -440,6 +441,11 @@ export const FLAG_TABLES = {
             help: "import: only send these names (repeatable or comma-separated)",
         },
     },
+    flow: {
+        repo: { value: true, help: "the repository (owner/name); default: this checkout's GitHub origin, when it is a repository of your workspace" },
+        period: { value: true, help: "24h | 2d | 3d | 1w | 2w | 4w | 12w | 26w (default: 2w)" },
+        granularity: { value: true, help: "hour | day (default: the period picks it: 1h for 24h, 2h for 2d, 3h for 3d, a day for weeks)" },
+    },
     team: {
         all: { value: false, help: "check every team, one request at a time" },
         stage: {
@@ -613,7 +619,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]",
+    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] [--fleet --dir <fleet directory>] [--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> | 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)",
@@ -646,6 +652,7 @@ export const VERB_USAGE = {
     identity: "identity linear <status|options|set> [<linearUserId>] [--json]",
     messages: "messages read --ticket CTC-N [--since SEQUENCE] [--json]",
     capabilities: "capabilities [--json]",
+    flow: "flow [--repo <owner/name>] [--period 24h|2d|3d|1w|2w|4w|12w|26w] [--granularity hour|day] [--json]   (a repository's open pull requests over time, one row per hour or day; needs login)",
     project: "project <list [--json] | wip-limit <get|set <n>|set default> [--team K] [--json]>",
     lease: "lease <take <ticket> --agent <seat> [--ttl <minutes>] | renew <ticket> (--commit <sha>|--artifact <path or id>|--finding <id>|--pr <number>) [--note <text>] [--agent <seat>] [--generation <n>] | release <ticket> [--agent <seat>] [--generation <n>] | show <ticket>> [--json]   (a seat's ticket lease: take, renew with new progress, release, read; needs login)",
     "codex-env": "codex-env --print [--codex-home <dir>] | --apply | --refresh [--json]   (the telemetry attributes naming the coding account and machine a Codex launch runs as; only --refresh waits on the network)",

package/dist/capabilities.js

@@ -35,6 +35,7 @@ export const CAPABILITIES = [
     { verb: "project wip-limit set", does: "set a project's new-start WIP limit (0 to 9999, or back to the workspace default)", needs: "admin", routes: [agent("POST", "team-wip-limit")], since: "0.13.1" },
     { verb: "repo status", does: "list visible repositories with their state, pause details and projects", needs: "member", routes: [agent("GET", "repos")], since: "0.16.27" },
     { verb: "repo pause|resume", does: "pause or resume a repository as a workspace owner or admin", needs: "admin", routes: [agent("GET", "repos"), agent("POST", "repos/pause"), agent("POST", "repos/resume")], since: "0.16.27" },
+    { verb: "flow", does: "print a repository's open pull request counts over time, one row per hour or per day", needs: "member", routes: [], since: "0.16.40" },
     { verb: "lease take|renew|release|show", does: "hold the ticket a seat works through a ticket lease that lapses without new progress, instead of a label", needs: "member", routes: [agent("POST", "ticket-lease/take"), agent("POST", "ticket-lease/renew"), agent("POST", "ticket-lease/release"), agent("GET", "ticket-lease")], since: "0.16.30" },
     { verb: "work available", does: "list tickets nobody holds, with the last holder and progress, and open pull requests no lease covers", needs: "member", routes: [], since: "0.16.30" },
     { verb: "repo agents-block", does: "add or refresh the one Catalyst block in a checkout's AGENTS.md, in the working tree, for the person to commit and open as a pull request", needs: "member", routes: [], since: "0.13.1" },

package/dist/cli.js

@@ -53,6 +53,7 @@ import { cmdLegacy } from "./legacy.js";
 import { cmdCodexEnv } from "./codex-env.js";
 import { codexAttributionAfterSetup, codexAttributionStatusLine, onlyCodexAttribution, removeCodexAttribution, } from "./codex-attribution.js";
 import { cmdIdentity } from "./identity.js";
+import { cmdFlow } from "./flow.js";
 import { cmdMessages } from "./messages.js";
 import { cmdConnections } from "./connections.js";
 import { cmdOnboard, onboardErrorJournal, onboardStatePath, readOnboardJournal, } from "./onboard.js";
@@ -120,6 +121,7 @@ export function usageText() {
         "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
         "  catalyst repo pause <owner/name> --reason <text> | repo resume <owner/name> [--reason <text>]   (owner or admin; reason: 1 to 500 trimmed characters)",
         "  catalyst repo status [--json]   (visible workspace repositories and their paused state; needs login)",
+        "  catalyst flow [--repo <owner/name>] [--period 2w] [--granularity hour|day] [--json]   (a repository's open pull requests over time; needs login)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst lease <take <ticket> --agent <seat> [--ttl <minutes>]|renew <ticket> --commit|--artifact|--finding|--pr <ref> [--note <text>]|release <ticket>|show <ticket>> [--json]   (a seat's ticket lease; needs login)",
         "  catalyst work available [--team K] [--json]   (tickets nobody holds and open pull requests no lease covers)",
@@ -582,6 +584,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdUpdate(args, ctx, deps.update);
             case "connections":
                 return await cmdConnections(args, ctx, deps.connections ?? {});
+            case "flow":
+                return await cmdFlow(args, ctx, deps.flow ?? {});
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());
@@ -646,6 +650,7 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "capabilities",
     "project",
     "repo",
+    "flow",
     "lease",
     "work",
     "legacy",

package/dist/flow.js

@@ -0,0 +1,104 @@
+import { resolve } from "node:path";
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { readLocalRepositoryName } from "./onboard-settings-context.js";
+import { bearerFor } from "./oauth.js";
+import { loadHttpSdk } from "./sdk.js";
+const REPO_RE = /^[^/\s]+\/[^/\s]+$/;
+function repoRequired(why) {
+    return new CliError(`flow needs a repository: pass --repo owner/name (${why})`, "repo-required", 2);
+}
+/** The zone the cloud cut the days in, from the answer's `boundary`; UTC when it names none. */
+function zoneOf(series) {
+    const b = series["boundary"];
+    if (b !== null && typeof b === "object" && "kind" in b) {
+        if (b.kind === "iana" && "timeZone" in b && typeof b.timeZone === "string") {
+            try {
+                new Intl.DateTimeFormat("en-CA", { timeZone: b.timeZone });
+                return { timeZone: b.timeZone };
+            }
+            catch {
+                // An unknown zone name prints in UTC rather than failing the whole read.
+            }
+        }
+        if (b.kind === "fixed-offset" && "offsetMinutes" in b && typeof b.offsetMinutes === "number" && Number.isFinite(b.offsetMinutes)) {
+            return { offsetMinutes: b.offsetMinutes };
+        }
+    }
+    return { timeZone: "UTC" };
+}
+/** One wall-clock formatter per series; a fixed-offset zone reads through shifted UTC. */
+function formatterFor(zone) {
+    return new Intl.DateTimeFormat("en-CA", {
+        timeZone: "timeZone" in zone ? zone.timeZone : "UTC",
+        year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23",
+        timeZoneName: "longOffset",
+    });
+}
+/** `±HH:MM` for a fixed offset's minutes. */
+function offsetText(minutes) {
+    const abs = Math.abs(minutes);
+    return `${minutes < 0 ? "-" : "+"}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
+function wallClock(ms, zone, fmt) {
+    const shifted = "offsetMinutes" in zone ? ms + zone.offsetMinutes * 60_000 : ms;
+    const parts = fmt.formatToParts(shifted);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    const offset = "offsetMinutes" in zone
+        ? offsetText(zone.offsetMinutes)
+        : part("timeZoneName").replace(/^GMT$/, "GMT+00:00").replace(/^GMT/, "");
+    return { date: `${part("year")}-${part("month")}-${part("day")}`, time: `${part("hour")}:${part("minute")}`, offset };
+}
+/** One line per bucket: the start in the boundary's zone (a date when every bucket starts at local
+ *  midnight, a local time with its offset otherwise), the open count, and `(now)` on the partial one. */
+function rows(series) {
+    const zone = zoneOf(series);
+    const fmt = formatterFor(zone);
+    const starts = series.columns.map((c) => wallClock(c.startMs, zone, fmt));
+    const daily = starts.every((w) => w.time === "00:00");
+    const when = starts.map((w) => (daily ? w.date : `${w.date}T${w.time}${w.offset}`));
+    const counts = series.columns.map((c) => (c.pr === null ? "unavailable" : String(c.pr.open)));
+    const width = Math.max(0, ...counts.map((c) => c.length));
+    return series.columns.map((c, i) => `${when[i]}  ${counts[i].padStart(width)}${c.partial ? "  (now)" : ""}`);
+}
+export async function cmdFlow(args, ctx, deps = {}) {
+    if (positionals(args).length > 0)
+        throw new UsageError("flow takes no positional arguments; name the repository with --repo owner/name");
+    const sdk = await loadHttpSdk();
+    const rawPeriod = flagString(args, "period");
+    const period = rawPeriod === undefined ? undefined : sdk.FLOW_PERIODS.find((p) => p === rawPeriod);
+    if (rawPeriod !== undefined && period === undefined)
+        throw new UsageError(`--period must be one of ${sdk.FLOW_PERIODS.join(", ")} (got "${rawPeriod}")`);
+    const rawGranularity = flagString(args, "granularity");
+    const granularity = rawGranularity === undefined ? undefined : sdk.FLOW_GRANULARITIES.find((g) => g === rawGranularity);
+    if (rawGranularity !== undefined && granularity === undefined)
+        throw new UsageError(`--granularity must be ${sdk.FLOW_GRANULARITIES.join(" or ")} (got "${rawGranularity}")`);
+    const named = flagString(args, "repo");
+    if (named !== undefined && !REPO_RE.test(named))
+        throw new UsageError(`--repo must be owner/name (got "${named}")`);
+    const cfg = requireConfig(ctx);
+    let repo = named;
+    if (repo === undefined) {
+        const local = await (deps.repoName ?? readLocalRepositoryName)(resolve("."));
+        if (local === null)
+            throw repoRequired("this directory is not a checkout with a GitHub origin");
+        const repositories = await (deps.repositories ?? (async () => (await loadContract(ctx, cfg)).doc.merge.repositories))();
+        const match = repositories.find((r) => `${r.owner}/${r.name}`.toLowerCase() === local);
+        if (match === undefined)
+            throw repoRequired(`this checkout's origin, ${local}, is not a repository of this workspace`);
+        repo = `${match.owner}/${match.name}`;
+    }
+    const createClient = deps.createClient ?? ((options) => sdk.createTenantClient(options));
+    const client = await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch });
+    const result = await client.flow.series({ repo, period, granularity });
+    if (result.outcome !== "ok")
+        throw new CliError(`flow for ${repo}: ${result.reason}`, result.outcome, 2, "status" in result ? result.status : undefined);
+    if (args.json)
+        ctx.stdout(JSON.stringify(result.series.columns));
+    else
+        for (const line of rows(result.series))
+            ctx.stdout(line);
+    return 0;
+}

package/dist/runner-auto-update.js

@@ -25,8 +25,16 @@ export const defaultRun = (cmd, args) => {
     return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
 };
 export const xml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+export const unxml = (value) => value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&amp;/g, "&");
 /** systemd's own quoting for one ExecStart/Environment word. */
 const unitWord = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+/** systemd's quoted words, as systemdUnits writes them. */
+export function unitWords(line) {
+    return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? "").replace(/\\(.)/g, "$1").replace(/%%/g, "%"));
+}
+/** The command the schedule runs. CTC-6384: a supervisor fleet's schedule adds --fleet, so each run
+ *  updates the fleet's compose.json in `dir` instead of a single runner's .env. */
+const updateArgs = (dir, fleet) => ["runner", "update", "--auto", ...(fleet ? ["--fleet"] : []), "--dir", dir];
 export function launchAgentPath(home) {
     return join(home, "Library", "LaunchAgents", `${AUTO_UPDATE_LABEL}.plist`);
 }
@@ -34,8 +42,8 @@ export function systemdUnitPaths(home) {
     const base = join(home, ".config", "systemd", "user");
     return { service: join(base, `${AUTO_UPDATE_UNIT}.service`), timer: join(base, `${AUTO_UPDATE_UNIT}.timer`) };
 }
-export function launchAgentPlist(deps, dir) {
-    const args = [...(deps.node ? [deps.node] : []), deps.cli, "runner", "update", "--auto", "--dir", dir];
+export function launchAgentPlist(deps, dir, fleet = false) {
+    const args = [...(deps.node ? [deps.node] : []), deps.cli, ...updateArgs(dir, fleet)];
     return [
         '<?xml version="1.0" encoding="UTF-8"?>',
         '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
@@ -54,7 +62,7 @@ export function launchAgentPlist(deps, dir) {
         "",
     ].join("\n");
 }
-export function systemdUnits(deps, dir) {
+export function systemdUnits(deps, dir, fleet = false) {
     return {
         service: [
             "[Unit]",
@@ -64,7 +72,7 @@ export function systemdUnits(deps, dir) {
             "Type=oneshot",
             `Environment=${unitWord(`PATH=${deps.path}`)}`,
             ...(deps.claude ? [`Environment=${unitWord(`${CLAUDE_PATH_ENV}=${deps.claude}`)}`] : []),
-            `ExecStart=${[deps.cli, "runner", "update", "--auto", "--dir", dir].map(unitWord).join(" ")}`,
+            `ExecStart=${[deps.cli, ...updateArgs(dir, fleet)].map(unitWord).join(" ")}`,
             "",
         ].join("\n"),
         timer: [
@@ -107,15 +115,41 @@ export function writeFileAtomic(path, text) {
     writeFileSync(temp, text, { mode: 0o644 });
     renameSync(temp, path);
 }
+/** The installed schedule's own command, read back from the file this CLI wrote. Null when the file
+ *  is missing or names no update directory. */
+function installedTarget(platform, home) {
+    let args;
+    try {
+        if (platform === "darwin") {
+            const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(readFileSync(launchAgentPath(home), "utf8"))?.[1];
+            args = array === undefined ? [] : [...array.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1] ?? ""));
+        }
+        else {
+            const exec = readFileSync(systemdUnitPaths(home).service, "utf8").split("\n").find((l) => l.startsWith("ExecStart="));
+            args = exec === undefined ? [] : unitWords(exec);
+        }
+    }
+    catch {
+        return null;
+    }
+    const at = args.indexOf("--dir");
+    const dir = at === -1 ? undefined : args[at + 1];
+    if (!args.includes("update") || dir === undefined || !dir.startsWith("/"))
+        return null;
+    return { fleet: args.includes("--fleet"), dir };
+}
 export function autoUpdateStatus(deps) {
     const platform = deps.platform ?? process.platform;
     const run = deps.run ?? defaultRun;
+    const target = () => installedTarget(platform, deps.home) ?? {};
     if (platform === "darwin") {
         const path = launchAgentPath(deps.home);
         if (!existsSync(path))
             return { state: "off", detail: "no_launch_agent" };
         const loaded = run("launchctl", ["print", `gui/${deps.uid ?? process.getuid?.() ?? 0}/${AUTO_UPDATE_LABEL}`]).status === 0;
-        return loaded ? { state: "on", detail: "launch_agent_loaded", path } : { state: "off", detail: "launch_agent_not_loaded" };
+        return loaded
+            ? { state: "on", detail: "launch_agent_loaded", path, ...target() }
+            : { state: "off", detail: "launch_agent_not_loaded", ...target() };
     }
     if (platform === "linux") {
         const { timer } = systemdUnitPaths(deps.home);
@@ -123,9 +157,9 @@ export function autoUpdateStatus(deps) {
             return { state: "off", detail: "no_timer" };
         const enabled = run("systemctl", ["--user", "is-enabled", `${AUTO_UPDATE_UNIT}.timer`]);
         if (enabled.status !== 0)
-            return { state: "off", detail: "timer_not_enabled" };
+            return { state: "off", detail: "timer_not_enabled", ...target() };
         const linger = lingering(run, deps.uid ?? process.getuid?.() ?? 0);
-        return { state: "on", detail: linger ? "timer_enabled" : "timer_enabled_without_linger", path: timer, linger };
+        return { state: "on", detail: linger ? "timer_enabled" : "timer_enabled_without_linger", path: timer, linger, ...target() };
     }
     return { state: "unsupported", detail: `platform_${platform}` };
 }
@@ -146,32 +180,34 @@ export function custodyNode(dir) {
         return null;
     }
 }
-/** Install and start the schedule. Rewrites the files every time, so a moved CLI or PATH is picked up. */
-export function enableAutoUpdate(deps, dir) {
+/** Install and start the schedule. Rewrites the files every time, so a moved CLI or PATH is picked up.
+ *  `fleet` schedules a supervisor fleet's update of the compose.json in `dir` (CTC-6384). */
+export function enableAutoUpdate(deps, dir, { fleet = false } = {}) {
     const platform = deps.platform ?? process.platform;
     const run = deps.run ?? defaultRun;
+    const target = { fleet, dir };
     if (platform === "darwin") {
         const uid = deps.uid ?? process.getuid?.() ?? 0;
         const path = launchAgentPath(deps.home);
-        const text = launchAgentPlist({ ...deps, node: deps.node === undefined ? custodyNode(dir) : deps.node }, dir);
+        const text = launchAgentPlist({ ...deps, node: deps.node === undefined ? custodyNode(dir) : deps.node }, dir, fleet);
         const unchanged = existsSync(path) && readFileSync(path, "utf8") === text;
         const domain = `gui/${uid}`;
         const loaded = run("launchctl", ["print", `${domain}/${AUTO_UPDATE_LABEL}`]).status === 0;
         if (unchanged && loaded)
-            return { state: "on", detail: "launch_agent_loaded", path };
+            return { state: "on", detail: "launch_agent_loaded", path, ...target };
         if (loaded)
             run("launchctl", ["bootout", `${domain}/${AUTO_UPDATE_LABEL}`]);
         writeFileAtomic(path, text);
         const boot = run("launchctl", ["bootstrap", domain, path]);
         return boot.status === 0
-            ? { state: "on", detail: "launch_agent_loaded", path }
+            ? { state: "on", detail: "launch_agent_loaded", path, ...target }
             : { state: "off", detail: `launchctl_bootstrap_failed:${boot.stderr.trim().slice(0, 160)}` };
     }
     if (platform === "linux") {
         if (run("systemctl", ["--user", "show-environment"]).status !== 0)
             return { state: "unsupported", detail: "no_systemd_user_manager" };
         const paths = systemdUnitPaths(deps.home);
-        const units = systemdUnits(deps, dir);
+        const units = systemdUnits(deps, dir, fleet);
         writeFileAtomic(paths.service, units.service);
         writeFileAtomic(paths.timer, units.timer);
         run("systemctl", ["--user", "daemon-reload"]);
@@ -180,7 +216,7 @@ export function enableAutoUpdate(deps, dir) {
             return { state: "off", detail: `systemctl_enable_failed:${enabled.stderr.trim().slice(0, 160)}` };
         const { linger, turnedOn } = ensureLingering(run, deps.uid ?? process.getuid?.() ?? 0);
         return { state: "on", detail: linger ? "timer_enabled" : "timer_enabled_without_linger", path: paths.timer, linger,
-            ...(turnedOn ? { lingerTurnedOn: true } : {}) };
+            ...(turnedOn ? { lingerTurnedOn: true } : {}), ...target };
     }
     return { state: "unsupported", detail: `platform_${platform}` };
 }

package/dist/runner-command.js

@@ -5,7 +5,7 @@ import { flagBool, flagString, positionals } from "./args.js";
 import { CliError, UsageError } from "./errors.js";
 import { autoUpdateStatus, custodyNode, disableAutoUpdate, enableAutoUpdate, scheduledPath, } from "./runner-auto-update.js";
 import { dockerRunnerUpdateEngine, readReleaseState, RELEASE_COMPONENTS, runnerDir, runRunnerUpdate, updateResultLines, lastProblem, lastProblemLines, } from "./runner-update.js";
-import { dockerFleetUpdateEngine, runFleetUpdate } from "./runner-update-fleet.js";
+import { dockerFleetUpdateEngine, postRollLines, readPostRollResult, runFleetPostRollCheck, runFleetUpdate } from "./runner-update-fleet.js";
 import { runUpdate, sharedReleaseRead, updateReportJson, updateReportLines } from "./update.js";
 import { effectivePolicy, readUpdatePolicy, setComponentPolicy } from "./update-policy.js";
 import { resolveClaude } from "./update-plugin.js";
@@ -37,8 +37,8 @@ function custodyRerun(ctx, deps, dir) {
     const run = deps.run ?? ((command, args, env) => spawnSync(command, [...args], { stdio: "inherit", env }).status ?? 1);
     return run(node, [script, ...rest], { ...ctx.env, [CUSTODY_RERUN_ENV]: "1" });
 }
-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"];
+const USAGE = "catalyst runner [status] | stop | start | uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off] [--fleet --dir <fleet directory>]";
+const UPDATE_FLAGS = ["check", "auto", "dir", "fleet", "post-roll-check"];
 function schedulerDeps(ctx, deps) {
     const cli = deps.scheduler?.cli ?? resolve(process.argv[1] ?? "catalyst");
     return {
@@ -89,7 +89,7 @@ export async function cmdRunner(args, ctx, deps = {}) {
     const action = parts[0];
     if (action === undefined || RUNNER_LIFECYCLE_ACTIONS.includes(action)) {
         if (UPDATE_FLAGS.some(flag => args.flags[flag] !== undefined))
-            throw new UsageError("--check, --auto, --dir and --fleet are only valid with runner update or auto-update");
+            throw new UsageError("--check, --auto, --dir, --fleet and --post-roll-check are only valid with runner update or auto-update");
         return cmdRunnerLifecycle(args, ctx, deps);
     }
     if (args.flags.yes !== undefined || args.flags["delete-checkouts"] !== undefined)
@@ -104,6 +104,18 @@ export async function cmdRunner(args, ctx, deps = {}) {
         const fleet = flagBool(args, "fleet");
         if (fleet && dirFlag === undefined)
             throw new UsageError("--fleet needs --dir, the directory that holds compose.json");
+        // The check a fleet update arms on the host 10 minutes after it applies (CTC-6564); only that timer passes it.
+        if (flagBool(args, "post-roll-check")) {
+            if (!fleet || dirFlag === undefined || check || auto)
+                throw new UsageError("--post-roll-check is run by the timer a fleet update arms: runner update --fleet --dir <dir> --post-roll-check");
+            const outcome = await runFleetPostRollCheck(deps.fleetEngine ?? dockerFleetUpdateEngine({ env: ctx.env }), { dir: dirFlag });
+            if (args.json)
+                ctx.stdout(JSON.stringify(outcome));
+            else
+                for (const line of outcome.result ? postRollLines(outcome.result) : [`Post-roll check: ${outcome.detail}.`])
+                    ctx.stdout(line);
+            return outcome.exitCode;
+        }
         if (!fleet && !check) {
             const rerun = custodyRerun(ctx, deps.custody ?? {}, dir());
             if (rerun !== null)
@@ -184,14 +196,27 @@ export async function cmdRunner(args, ctx, deps = {}) {
                     ctx.stdout(line);
             return result.exitCode;
         }
+        // A fleet check also names the last post-roll verdict (CTC-6564).
+        if (check && fleet && !auto) {
+            const verdict = readPostRollResult(dir());
+            if (args.json)
+                ctx.stdout(JSON.stringify({ ...result, lastPostRoll: verdict }));
+            else
+                for (const line of [...updateResultLines(result), ...postRollLines(verdict)])
+                    ctx.stdout(line);
+            return result.exitCode;
+        }
         return print(result, await components(result));
     }
     if (action === "auto-update" && parts.length <= 2) {
         const mode = parts[1] ?? "status";
+        const fleet = flagBool(args, "fleet");
+        if (mode === "on" && fleet && dirFlag === undefined)
+            throw new UsageError("--fleet needs --dir, the directory that holds compose.json");
         const scheduler = schedulerDeps(ctx, deps);
         let status;
         if (mode === "on")
-            status = enableAutoUpdate(scheduler, dir());
+            status = enableAutoUpdate(scheduler, dir(), { fleet });
         else if (mode === "off")
             status = disableAutoUpdate(scheduler);
         else if (mode === "status")
@@ -207,8 +232,12 @@ export async function cmdRunner(args, ctx, deps = {}) {
             const state = mode === "status" && dirFlag !== undefined ? readReleaseState(dirFlag) : undefined;
             ctx.stdout(JSON.stringify({ ...status, ...(state ? { release: state } : {}) }));
         }
-        else
+        else {
             ctx.stdout(statusLine(status));
+            // A single runner's schedule prints what it always has; a fleet's says so, and for which directory.
+            if (status.state === "on" && status.fleet)
+                ctx.stdout(`This is a supervisor fleet's schedule: it updates the compose.json in ${status.dir}.`);
+        }
         return status.state === "on" || mode !== "on" ? 0 : 1;
     }
     throw new UsageError(USAGE);

package/dist/runner-update-fleet.js

@@ -1,6 +1,8 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { dockerRunnerEngine, prepareRunnerImages, spawnDocker } from "./onboard-runner.js";
+import { defaultRun } from "./runner-auto-update.js";
 import { decideRelease, DESIRED_RELEASE_SCRIPT, HOST_ID, isRecord, readReleaseState, releaseLock, takeLock, writePrivateAtomic, writeReleaseState, } from "./runner-update.js";
 // `catalyst runner update --fleet <dir>`: the same approved release, applied to a multi-team
 // supervisor fleet (CTC-6530). One supervisor container serves several scopes from a Compose file
@@ -20,6 +22,12 @@ import { decideRelease, DESIRED_RELEASE_SCRIPT, HOST_ID, isRecord, readReleaseSt
 // no restart and log no `host_not_ready` for those scopes. Otherwise the previous `compose.json` comes
 // back and the supervisor is recreated on it. That scope set is saved before the recreate and removed
 // once it qualifies or rolls back, so a run killed in between is finished by the next one.
+//
+// A release can qualify and then stop receiving work minutes later (CTC-6564). A successful apply
+// arms a check on the host, outside the calling process, for 10 minutes later: it reads the supervisor's
+// log since the roll began and, when the release was granted no work and the fleet's acquires got no
+// answer, restores the saved previous `compose.json`. `runner update --fleet --post-roll-check` is
+// that check; only the armed timer runs it.
 export const FLEET_COMPOSE_FILE = "compose.json";
 export const PREVIOUS_COMPOSE_FILE = "compose.release-previous.json";
 const CANDIDATE_COMPOSE_FILE = "compose.release-candidate.json";
@@ -34,6 +42,14 @@ const QUALIFY_MIN_MS = 90_000;
 const QUALIFY_DEADLINE_MS = 240_000;
 const QUALIFY_POLL_MS = 10_000;
 const CHILD_NAME_PREFIX = "catalyst-pa_";
+/** What a successful apply leaves for the check: the bytes it wrote and when the roll began. */
+export const POST_ROLL_ARMED_FILE = "post-roll-armed.json";
+/** The check's last verdict, beside `release-state.json`. */
+export const POST_ROLL_RESULT_FILE = "post-roll-result.json";
+export const POST_ROLL_DELAY_MS = 10 * 60_000;
+const POST_ROLL_UNIT = "catalyst-fleet-post-roll";
+/** No-response acquire retries, with no grants, that count a release as failing. */
+const POST_ROLL_MAX_NO_RESPONSE = 3;
 /** The two image fields in a fleet `compose.json`, or null when the file is not a fleet layout. */
 export function fleetImages(compose) {
     const supervisor = isRecord(compose) && isRecord(compose.services) ? compose.services.supervisor : null;
@@ -104,6 +120,112 @@ function clearInFlight(dir) {
         // Already gone.
     }
 }
+const removeFile = (path) => {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Already gone.
+    }
+};
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const POST_ROLL_VERDICTS = ["PASS", "STANDS_IDLE", "ROLLED_BACK", "ROLLBACK_REFUSED", "ROLLBACK_FAILED"];
+const numberOrNull = (value) => (typeof value === "number" && Number.isSafeInteger(value) ? value : null);
+const stringOrNull = (value) => (typeof value === "string" ? value : null);
+function readPostRollArmed(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, POST_ROLL_ARMED_FILE), "utf8"));
+        if (!isRecord(parsed) || parsed.version !== 1)
+            return null;
+        const sinceMs = numberOrNull(parsed.sinceMs);
+        if (sinceMs === null || typeof parsed.composeSha256 !== "string")
+            return null;
+        return {
+            version: 1,
+            sinceMs,
+            composeSha256: parsed.composeSha256,
+            generation: numberOrNull(parsed.generation),
+            releaseId: stringOrNull(parsed.releaseId),
+            fromGeneration: numberOrNull(parsed.fromGeneration),
+            armedAtMs: numberOrNull(parsed.armedAtMs) ?? sinceMs,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** The last post-roll check's record, or null when there is none. */
+export function readPostRollResult(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, POST_ROLL_RESULT_FILE), "utf8"));
+        if (!isRecord(parsed) || parsed.version !== 1 || typeof parsed.verdict !== "string" || !POST_ROLL_VERDICTS.includes(parsed.verdict))
+            return null;
+        if (typeof parsed.at !== "string" || typeof parsed.since !== "string")
+            return null;
+        return {
+            version: 1,
+            at: parsed.at,
+            since: parsed.since,
+            granted: numberOrNull(parsed.granted) ?? 0,
+            noResponse: numberOrNull(parsed.noResponse) ?? 0,
+            answered: numberOrNull(parsed.answered) ?? 0,
+            verdict: parsed.verdict,
+            generation: numberOrNull(parsed.generation),
+            releaseId: stringOrNull(parsed.releaseId),
+            ...(parsed.rolledBackFrom !== undefined ? { rolledBackFrom: numberOrNull(parsed.rolledBackFrom) } : {}),
+            ...(parsed.rolledBackTo !== undefined ? { rolledBackTo: numberOrNull(parsed.rolledBackTo) } : {}),
+            ...(typeof parsed.reason === "string" ? { reason: parsed.reason } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const VERDICT_TEXT = {
+    PASS: "passed: the release was granted work",
+    STANDS_IDLE: "left the release in place: no work was granted and nothing showed a failure",
+    ROLLED_BACK: "rolled the release back: it was granted no work or its supervisor was not running",
+    ROLLBACK_REFUSED: "found no work granted and did not roll back",
+    ROLLBACK_FAILED: "tried to roll back and could not confirm the supervisor",
+};
+/** One line naming the last post-roll verdict, for `runner update --check --fleet`. */
+export function postRollLines(result) {
+    if (result === null)
+        return [];
+    const detail = [
+        ...(result.verdict === "ROLLED_BACK" ? [`back to generation ${result.rolledBackTo ?? "none"}`] : result.reason ? [result.reason] : []),
+        `generation ${result.generation ?? "none"}`,
+        `since ${result.since}: ${result.granted} granted, ${result.noResponse} no response, ${result.answered} answered`,
+    ];
+    return [`The last post-roll check, at ${result.at}, ${VERDICT_TEXT[result.verdict]} (${detail.join("; ")}).`];
+}
+const eventLines = (text, event) => text.split("\n").filter((line) => new RegExp(`"event"\\s*:\\s*"${event}"`).test(line));
+/** The counts the post-roll rule reads from the supervisor's log since the roll began. `answered` is
+ *  informational: an idle supervisor whose acquire gets an empty queue may log nothing at all. */
+export function postRollCounts(text) {
+    const granted = eventLines(text, "work_granted").length;
+    const refused = eventLines(text, "acquire_refused").length;
+    const none = eventLines(text, "acquire_none").length;
+    const noResponse = text.split("\n").filter((line) => line.includes("acquire_retry") && line.includes("(no response)")).length;
+    return { granted, noResponse, answered: granted + refused + none };
+}
+/** Whether a release with these counts stopped receiving work: nothing granted since the roll began and
+ *  at least three acquire retries that got no response. Silence alone is not a failure, because a healthy
+ *  idle host logs nothing; a supervisor that is not running is judged separately, from the container. */
+export const postRollFailing = (counts) => counts.granted === 0 && counts.noResponse >= POST_ROLL_MAX_NO_RESPONSE;
+/** Record what the apply wrote and ask the engine for the check. The note joins the result's detail
+ *  when the check could not be armed; the apply itself still succeeded. */
+async function armPostRollCheck(engine, dir, armed, signal) {
+    try {
+        writePrivateAtomic(join(dir, POST_ROLL_ARMED_FILE), `${JSON.stringify(armed, null, 2)}\n`);
+        // The verdict on an earlier release says nothing about this one.
+        removeFile(join(dir, POST_ROLL_RESULT_FILE));
+        return (await engine.armPostRollCheck(dir, POST_ROLL_DELAY_MS, signal)) ? "" : ";post_roll_check_not_armed";
+    }
+    catch {
+        return ";post_roll_check_not_armed";
+    }
+}
 export async function runFleetUpdate(engine, options) {
     const { dir } = options;
     const now = options.now ?? Date.now;
@@ -152,6 +274,11 @@ async function update(engine, options, now) {
     const target = { runner: release.images.runner.reference, supervisor: release.images.supervisor.reference };
     const changed = ["runner", "supervisor"].filter((c) => current[c] !== target[c]);
     const tagged = { releaseId: release.releaseId };
+    // A release the post-roll check rolled back stays rolled back while it is the approved one; a newer
+    // generation is applied normally (CTC-6564).
+    const rolled = readPostRollResult(dir);
+    if (changed.length > 0 && rolled?.verdict === "ROLLED_BACK" && rolled.releaseId === release.releaseId && rolled.generation === release.generation)
+        return done("rolled_back", `post_roll_rolled_back:granted=${rolled.granted},no_response=${rolled.noResponse},answered=${rolled.answered}`, { ...tagged, generation: release.generation, exitCode: 1 });
     const live = await engine.supervisor(dir, project, signal);
     if (live === undefined)
         return done("retained", "docker_unavailable", tagged);
@@ -223,6 +350,7 @@ async function update(engine, options, now) {
     if (childrenBefore === null)
         return done("retained", "docker_unavailable", tagged);
     // From here the machine changes. The previous file is the rollback.
+    const rollStartMs = now();
     if (changed.length > 0)
         writePrivateAtomic(join(dir, PREVIOUS_COMPOSE_FILE), composeText);
     writePrivateAtomic(join(dir, IN_FLIGHT_FILE), `${JSON.stringify({ version: 1, scopes: [...scopes].sort(), atMs: now() })}\n`);
@@ -239,7 +367,11 @@ async function update(engine, options, now) {
                 const after = childrenAfter[id];
                 return before.running && after?.running === true && after.fingerprint !== before.fingerprint;
             }).length;
-        const detail = changed.length > 0 ? `updated:${changed.join(",")}` : "reconciled";
+        const armed = {
+            version: 1, sinceMs: rollStartMs, composeSha256: sha256(candidateText), generation: release.generation,
+            releaseId: release.releaseId, fromGeneration: state.generation, armedAtMs: now(),
+        };
+        const detail = (changed.length > 0 ? `updated:${changed.join(",")}` : "reconciled") + await armPostRollCheck(engine, dir, armed, signal);
         const previous = changed.length > 0 ? current : null;
         return disturbed === 0
             ? record("updated", detail, previous)
@@ -247,14 +379,104 @@ async function update(engine, options, now) {
     }
     if (rollbackText === null || rollbackImages === null)
         return done("failed", "new_supervisor_not_qualified_no_previous", { ...tagged, exitCode: 1 });
-    writePrivateAtomic(composePath, rollbackText);
-    const restored = (await engine.recreate(dir, project, signal)) &&
+    const restored = (await restoreCompose(engine, dir, project, rollbackText, signal)) &&
         (await qualify(engine, dir, project, rollbackImages, scopes, options, now));
     // A rollback that did not qualify keeps the baseline for the next run.
     if (restored)
         clearInFlight(dir);
     return done(restored ? "rolled_back" : "failed", restored ? "new_supervisor_not_qualified" : "rollback_not_qualified", { ...tagged, exitCode: 1 });
 }
+/** Put `text` back as `compose.json` and recreate the supervisor alone on it. */
+async function restoreCompose(engine, dir, project, text, signal) {
+    writePrivateAtomic(join(dir, FLEET_COMPOSE_FILE), text);
+    return engine.recreate(dir, project, signal);
+}
+/** The check a successful apply armed, run on the host 10 minutes later (CTC-6564). A release whose
+ *  supervisor is not running, or that was granted no work while three acquire retries got no response,
+ *  goes back to the saved previous `compose.json`, but only if `compose.json` still holds the bytes the
+ *  apply wrote. A running supervisor with no grants and fewer no-response retries stands. */
+export async function runFleetPostRollCheck(engine, options) {
+    const { dir, signal } = options;
+    const now = options.now ?? Date.now;
+    const stay = (detail, exitCode = 0) => ({ detail, result: null, exitCode });
+    if (!existsSync(join(dir, FLEET_COMPOSE_FILE)))
+        return stay("fleet_not_installed", 1);
+    const armed = readPostRollArmed(dir);
+    if (armed === null)
+        return stay("no_post_roll_check_armed");
+    const lock = takeLock(dir, now());
+    if (lock === null)
+        return stay("update_running");
+    try {
+        const composeText = readFileSync(join(dir, FLEET_COMPOSE_FILE), "utf8");
+        let compose;
+        try {
+            compose = JSON.parse(composeText);
+        }
+        catch {
+            compose = null;
+        }
+        const project = isRecord(compose) && typeof compose.name === "string" ? compose.name : "";
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(project))
+            return stay("fleet_compose_unrecognized", 1);
+        const live = await engine.supervisor(dir, project, signal);
+        if (live === undefined)
+            return stay("docker_unavailable", 1);
+        const since = new Date(armed.sinceMs).toISOString();
+        // A missing or stopped supervisor is a failure on its own; its log is not read.
+        const notRunning = live === null || !live.running;
+        let counts = { granted: 0, noResponse: 0, answered: 0 };
+        if (!notRunning) {
+            const text = await engine.logs(live.id, since, signal);
+            if (text === null)
+                return stay("docker_unavailable", 1);
+            counts = postRollCounts(text);
+        }
+        const finish = (verdict, extra = {}, exitCode = 0) => {
+            const result = {
+                version: 1, at: new Date(now()).toISOString(), since, ...counts, verdict,
+                generation: armed.generation, releaseId: armed.releaseId, ...extra,
+            };
+            writePrivateAtomic(join(dir, POST_ROLL_RESULT_FILE), `${JSON.stringify(result, null, 2)}\n`);
+            removeFile(join(dir, POST_ROLL_ARMED_FILE));
+            return { detail: verdict, result, exitCode };
+        };
+        if (!notRunning) {
+            if (counts.granted > 0)
+                return finish("PASS");
+            if (!postRollFailing(counts))
+                return finish("STANDS_IDLE");
+        }
+        const refuse = (reason) => finish("ROLLBACK_REFUSED", { reason }, 1);
+        if (sha256(composeText) !== armed.composeSha256)
+            return refuse("compose_changed_since_roll");
+        let previousText;
+        let previous;
+        try {
+            previousText = readFileSync(join(dir, PREVIOUS_COMPOSE_FILE), "utf8");
+            previous = fleetImages(JSON.parse(previousText));
+        }
+        catch {
+            return refuse("no_previous_compose");
+        }
+        if (previous === null)
+            return refuse("no_previous_compose");
+        // The apply removed the images it replaced, so the previous ones may need pulling again.
+        const unprepared = await engine.prepare([previous.runner, previous.supervisor], signal);
+        if (unprepared !== null)
+            return finish("ROLLBACK_FAILED", { reason: unprepared }, 1);
+        const restored = await restoreCompose(engine, dir, project, previousText, signal);
+        const after = restored ? await engine.supervisor(dir, project, signal) : null;
+        const running = !!after && after.running && after.image === previous.supervisor && after.runnerImage === previous.runner;
+        const moved = { rolledBackFrom: armed.generation, rolledBackTo: armed.fromGeneration };
+        return running
+            ? finish("ROLLED_BACK", { ...moved, reason: notRunning ? "supervisor_not_running" : "no_work_granted" }, 1)
+            : finish("ROLLBACK_FAILED", { ...moved, reason: restored ? "supervisor_not_running" : "recreate_failed" }, 1);
+    }
+    finally {
+        releaseLock(dir, lock);
+    }
+}
 /** The recreated supervisor runs `images`, stays up with no restart, logs no `host_not_ready` for a
  *  scope it must serve, and qualifies every one of `scopes`, held for the minimum window. */
 async function qualify(engine, dir, project, images, scopes, options, now) {
@@ -438,5 +660,28 @@ export function dockerFleetUpdateEngine(deps = {}) {
             for (const ref of images)
                 await docker(["image", "rm", ref], { signal, timeoutMs: 120_000 });
         },
+        // A transient systemd timer outlives this process and the operator's session. Root's runs under the
+        // system manager; anyone else's runs under their user manager, which needs lingering to outlive a logout.
+        async armPostRollCheck(dir, delayMs) {
+            const timer = deps.timer ?? {};
+            if ((timer.platform ?? process.platform) !== "linux")
+                return false;
+            const command = timer.command ?? (process.argv[1] ? [process.execPath, resolve(process.argv[1])] : null);
+            if (command === null)
+                return false;
+            const run = timer.run ?? defaultRun;
+            const manager = (timer.uid ?? process.getuid?.()) === 0 ? [] : ["--user"];
+            const source = deps.env ?? process.env;
+            const carried = ["PATH", "HOME"].flatMap((key) => (source[key] ? [`--setenv=${key}=${source[key]}`] : []));
+            try {
+                // A timer armed by an earlier apply is replaced, not duplicated.
+                run("systemctl", [...manager, "stop", `${POST_ROLL_UNIT}.timer`, `${POST_ROLL_UNIT}.service`]);
+                return run("systemd-run", [...manager, "--quiet", "--collect", `--unit=${POST_ROLL_UNIT}`, `--on-active=${Math.ceil(delayMs / 1000)}s`,
+                    "--description=Catalyst fleet post-roll check", ...carried, "--", ...command, "runner", "update", "--fleet", "--dir", dir, "--post-roll-check"]).status === 0;
+            }
+            catch {
+                return false;
+            }
+        },
     };
 }

package/dist/runner-update.js

@@ -601,7 +601,7 @@ const OUTCOME_TEXT = {
     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.",
+    rolled_back: "The new release was rolled back, so the previous images were restored.",
     failed: "The update could not finish. Look at the runner with docker compose ps.",
 };
 /** The last run's record when it ended badly: a failed or rolled-back update a person should know

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.39",
+  "version": "0.16.40",
   "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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — 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.39 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.40 — written in this repository for customer accounts -->
 
 # What's happening