@indigoai-us/hq-cli 5.135.0 → 5.136.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.136.0] — 2026-09-23
+
+### Added
+
+- Your local bots can now do work on a repeating schedule. Ask a company bot for something regular — "check the overnight errors every weekday morning" — and it sets the schedule up itself; you can also see and remove its schedules with `hq bot jobs <name>`. The schedule is kept in the cloud, not on your computer. If the Mac is asleep when a run is due, the run happens as a catch-up when it wakes, as long as that is within about an hour, and the bot's report says it ran late; after a longer outage that run is skipped and the job carries on at its next scheduled time. Personal bots can't schedule work yet.
+
 ## [5.135.0] — 2026-09-23
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -7318,6 +7318,37 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Expected transfer size";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "jobs";
+        readonly description: "Show, schedule, or remove a bot's recurring jobs (the schedule runs in the cloud, not on this computer)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <name>";
+        readonly arguments: readonly [{
+            readonly name: "name";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--add <what>";
+            readonly description: "Schedule new work, in plain language";
+        }, {
+            readonly flags: "--every <when>";
+            readonly description: "How often, in plain language (e.g. \"every weekday at 9am\")";
+        }, {
+            readonly flags: "--cron <expr>";
+            readonly description: "How often, as a cron expression (e.g. \"0 9 * * 1-5\")";
+        }, {
+            readonly flags: "--tz <zone>";
+            readonly description: "IANA timezone for the schedule (default: this computer's)";
+        }, {
+            readonly flags: "--rm <jobId>";
+            readonly description: "Remove a scheduled job";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "promote";
         readonly description: "Move this local bot to cloud compute, preserving its identity and private context";

package/dist/command-catalog.generated.js

@@ -9463,6 +9463,47 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "jobs",
+                "description": "Show, schedule, or remove a bot's recurring jobs (the schedule runs in the cloud, not on this computer)",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <name>",
+                "arguments": [
+                    {
+                        "name": "name",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--add <what>",
+                        "description": "Schedule new work, in plain language"
+                    },
+                    {
+                        "flags": "--every <when>",
+                        "description": "How often, in plain language (e.g. \"every weekday at 9am\")"
+                    },
+                    {
+                        "flags": "--cron <expr>",
+                        "description": "How often, as a cron expression (e.g. \"0 9 * * 1-5\")"
+                    },
+                    {
+                        "flags": "--tz <zone>",
+                        "description": "IANA timezone for the schedule (default: this computer's)"
+                    },
+                    {
+                        "flags": "--rm <jobId>",
+                        "description": "Remove a scheduled job"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "promote",
                 "description": "Move this local bot to cloud compute, preserving its identity and private context",

package/dist/commands/bot-jobs.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `hq bot jobs` — a local bot's recurring scheduled work.
+ *
+ *   hq bot jobs <botName>                                  list
+ *   hq bot jobs <botName> --add "<what to do>" --every "<plain english>"
+ *   hq bot jobs <botName> --add "<what to do>" --cron "0 9 * * 1-5"
+ *   hq bot jobs <botName> --rm <jobId>
+ *
+ * The schedule lives in the cloud, never on this computer: hq-pro-agents holds
+ * the job and fires it on an EventBridge schedule, and the bot's inbox loop
+ * runs the fired run (see lib/bot/job-run.ts). Nothing here writes a crontab,
+ * a launchd plist, or a systemd unit — by rule.
+ *
+ * The routes are self-only per agent, so every call uses the BOT's own machine
+ * identity — the same credential path its turns use — not the owner's session.
+ */
+import { execFileSync } from "node:child_process";
+import type { Command } from "commander";
+import { BotApi, type BotJobRecord, type CreateJobInput } from "../lib/bot/api.js";
+import { type BotConfig, type BotKind } from "../lib/bot/config.js";
+/** Mirrors hq-pro-agents `MIN_RECURRING_INTERVAL_SECONDS`. */
+export declare const MIN_RECURRING_INTERVAL_SECONDS: number;
+/** Mirrors hq-pro-agents `DEFAULT_MAX_ACTIVE_JOBS_PER_AGENT`. */
+export declare const MAX_ACTIVE_JOBS_PER_AGENT = 25;
+/** Mirrors hq-pro-agents `MAX_PROMPT_BYTES`. */
+export declare const MAX_PROMPT_BYTES: number;
+export declare class BotJobsError extends Error {
+    readonly expected: true;
+}
+/** The machine's own IANA zone, so "9am" means 9am where the owner lives. */
+export declare function machineTimezone(): string;
+/**
+ * Standard 5-field cron → the EventBridge form the cloud stores.
+ *
+ * EventBridge cron has SIX fields (a trailing year), numbers its days of week
+ * 1–7 with SUNDAY = 1 (standard cron uses 0–6 with SUNDAY = 0), and refuses
+ * `*` in BOTH the day-of-month and day-of-week fields — exactly one must be
+ * `?`. An expression that is already `cron(...)` or `rate(...)` is passed
+ * through untouched.
+ */
+export declare function toEventBridgeCron(expr: string): string;
+/**
+ * The smallest gap a recurring expression can produce, in seconds, or null
+ * when it is not a recognised rate()/cron() form. Mirrors hq-pro-agents
+ * `recurringIntervalSeconds` so the CLI can refuse a sub-floor schedule with
+ * the server's own reason instead of a round-trip and a raw 400.
+ */
+export declare function recurringIntervalSeconds(expr: string): number | null;
+/** Refuse a schedule the cloud would refuse, with the cloud's own reason. */
+export declare function assertScheduleWithinFloor(expr: string): void;
+export interface ParsedSchedule {
+    /** Standard 5-field cron, as the HQ helper emits it. */
+    cron: string;
+    timezone: string;
+    /** Plain words for the schedule, when the helper supplied them. */
+    human?: string;
+}
+export declare function scheduleHelperPath(hqRoot: string): string;
+/**
+ * Plain English → cron, using HQ's OWN helper (`core/scripts/jobs-schedule-parse.sh`)
+ * so `hq bot jobs --every` and the `/schedule` command agree on what "every
+ * weekday morning" means. When the helper is not in this HQ root, the caller is
+ * told to pass `--cron` instead rather than getting a second, divergent parser.
+ */
+export declare function parseScheduleText(text: string, opts: {
+    hqRoot: string;
+    timezone: string;
+    exec?: typeof execFileSync;
+    exists?: (p: string) => boolean;
+}): ParsedSchedule;
+/** The create body the cloud expects, with the client-side limits enforced first. */
+export declare function buildCreateJobBody(input: {
+    prompt: string;
+    cron: string;
+    timezone: string;
+    context?: Record<string, unknown>;
+}): CreateJobInput;
+/** A schedule in plain words, falling back to the raw expression. */
+export declare function describeSchedule(job: BotJobRecord): string;
+/** A small humaniser for the shapes `--every` actually produces. */
+export declare function cronInWords(expr: string): string | null;
+/** "never run yet" / "succeeded 2026-09-15 09:00 UTC". */
+export declare function describeLastRun(job: BotJobRecord): string;
+export declare function formatJobsList(botName: string, jobs: BotJobRecord[]): string;
+/**
+ * Turn a jobs-route failure into one plain line.
+ *
+ * Personal bots are refused by the cloud today: their JWT carries the owner's
+ * `per_…` company claim and the jobs routes require a `cmp_…`, so the fail-closed
+ * guard answers 403 `CROSS_AGENT_JOB` (hq-pro-agents jobs/errors.ts
+ * `CrossAgentJobError`). That server fix is a separate change; until it lands the
+ * refusal must read as "not available yet for this kind of bot", not as a raw 403.
+ * Once the server accepts personal bots the refusal simply stops happening — no
+ * client change needed.
+ *
+ * ONLY that exact code is rewritten. Every other 403, and every 404, keeps its
+ * real message: masking them would hide a genuinely missing job or a different
+ * permission problem behind copy about the wrong thing.
+ */
+export declare function jobsErrorMessage(err: unknown, ctx: {
+    botName: string;
+    kind: BotKind;
+}): string;
+export interface BotJobsDeps {
+    requireBot(name: string): {
+        name: string;
+        dir: string;
+        config: BotConfig;
+    };
+    botTokenSupplier(dir: string): () => Promise<string>;
+    /** Test seam: the jobs client for a bot directory. */
+    apiFor?(dir: string): Pick<BotApi, "listJobs" | "createJob" | "cancelJob">;
+    parseSchedule?: typeof parseScheduleText;
+    timezone?: () => string;
+    out?: (line: string) => void;
+}
+export interface BotJobsOptions {
+    add?: string;
+    every?: string;
+    cron?: string;
+    tz?: string;
+    rm?: string;
+    json?: boolean;
+}
+export declare function runBotJobs(nameArg: string, opts: BotJobsOptions, deps: BotJobsDeps): Promise<void>;
+export declare function registerBotJobsCommand(bot: Command, deps: BotJobsDeps): void;
+//# sourceMappingURL=bot-jobs.d.ts.map

package/dist/commands/bot-jobs.js

@@ -0,0 +1,445 @@
+/**
+ * `hq bot jobs` — a local bot's recurring scheduled work.
+ *
+ *   hq bot jobs <botName>                                  list
+ *   hq bot jobs <botName> --add "<what to do>" --every "<plain english>"
+ *   hq bot jobs <botName> --add "<what to do>" --cron "0 9 * * 1-5"
+ *   hq bot jobs <botName> --rm <jobId>
+ *
+ * The schedule lives in the cloud, never on this computer: hq-pro-agents holds
+ * the job and fires it on an EventBridge schedule, and the bot's inbox loop
+ * runs the fired run (see lib/bot/job-run.ts). Nothing here writes a crontab,
+ * a launchd plist, or a systemd unit — by rule.
+ *
+ * The routes are self-only per agent, so every call uses the BOT's own machine
+ * identity — the same credential path its turns use — not the owner's session.
+ */
+import chalk from "chalk";
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { BotApi, BotApiError } from "../lib/bot/api.js";
+import { effectiveBotKind } from "../lib/bot/config.js";
+// ─── Schedule translation ────────────────────────────────────────────────────
+/** Mirrors hq-pro-agents `MIN_RECURRING_INTERVAL_SECONDS`. */
+export const MIN_RECURRING_INTERVAL_SECONDS = 5 * 60;
+/** Mirrors hq-pro-agents `DEFAULT_MAX_ACTIVE_JOBS_PER_AGENT`. */
+export const MAX_ACTIVE_JOBS_PER_AGENT = 25;
+/** Mirrors hq-pro-agents `MAX_PROMPT_BYTES`. */
+export const MAX_PROMPT_BYTES = 16 * 1024;
+export class BotJobsError extends Error {
+    expected = true;
+}
+function refuse(message) {
+    throw new BotJobsError(message);
+}
+/** The machine's own IANA zone, so "9am" means 9am where the owner lives. */
+export function machineTimezone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+/**
+ * Standard 5-field cron → the EventBridge form the cloud stores.
+ *
+ * EventBridge cron has SIX fields (a trailing year), numbers its days of week
+ * 1–7 with SUNDAY = 1 (standard cron uses 0–6 with SUNDAY = 0), and refuses
+ * `*` in BOTH the day-of-month and day-of-week fields — exactly one must be
+ * `?`. An expression that is already `cron(...)` or `rate(...)` is passed
+ * through untouched.
+ */
+export function toEventBridgeCron(expr) {
+    const trimmed = expr.trim();
+    // An explicit cron(...) / rate(...) is the caller saying "this is already the
+    // cloud's own syntax" — passed through untranslated, on purpose.
+    if (/^(cron|rate)\s*\(/i.test(trimmed))
+        return trimmed;
+    const fields = trimmed.split(/\s+/).filter(Boolean);
+    if (fields.length === 6) {
+        // Six BARE fields are ambiguous: EventBridge's sixth field is a trailing
+        // year, Quartz's first is leading seconds. Guessing wrong silently moves
+        // every run. Make the caller say which they mean.
+        refuse(`"${trimmed}" has six fields, and I can't tell whether that is an EventBridge expression ` +
+            `(minute hour day-of-month month day-of-week year) or a Quartz one (leading seconds) — ` +
+            `reading it the wrong way would schedule the job at the wrong time. Pass five fields ` +
+            `("0 9 * * 1-5"), or wrap it yourself as cron(...) if it is already an EventBridge expression.`);
+    }
+    if (fields.length !== 5) {
+        refuse(`"${trimmed}" is not a cron expression. A cron expression has five fields: ` +
+            `minute hour day-of-month month day-of-week (for example "0 9 * * 1-5").`);
+    }
+    const [minute, hour, month] = [fields[0], fields[1], fields[3]];
+    let dayOfMonth = fields[2];
+    let dayOfWeek = fields[4];
+    if (dayOfWeek === "*" || dayOfWeek === "?") {
+        dayOfWeek = "?";
+        if (dayOfMonth === "?")
+            dayOfMonth = "*";
+    }
+    else {
+        dayOfWeek = shiftDayOfWeek(dayOfWeek);
+        if (dayOfMonth === "*")
+            dayOfMonth = "?";
+    }
+    return `cron(${minute} ${hour} ${dayOfMonth} ${month} ${dayOfWeek} *)`;
+}
+/**
+ * Standard 0–6 (SUN=0, and 7 also SUN) → EventBridge 1–7 (SUN=1).
+ *
+ * Mapped per TERM, not per digit. Shifting digits individually turned a range
+ * that wraps past Sunday — "6-0" (Sat–Sun), "5-1" (Fri–Mon) — into "7-1" /
+ * "6-2": reversed or plain wrong, and silently so. Such a range is refused with
+ * the list form that does work.
+ */
+function shiftDayOfWeek(field) {
+    return field
+        .split(",")
+        .map((term) => shiftDayOfWeekTerm(term.trim()))
+        .join(",");
+}
+function shiftDay(n) {
+    return (n % 7) + 1;
+}
+function shiftDayOfWeekTerm(term) {
+    const step = term.match(/^(.+)\/(\d+)$/);
+    if (step)
+        return `${shiftDayOfWeekTerm(step[1])}/${step[2]}`;
+    const range = term.match(/^(\d+)-(\d+)$/);
+    if (range) {
+        const from = shiftDay(Number(range[1]));
+        const to = shiftDay(Number(range[2]));
+        if (from > to) {
+            const days = [];
+            for (let d = Number(range[1]);; d = (d + 1) % 7) {
+                days.push(d);
+                if (d === Number(range[2]) % 7)
+                    break;
+                if (days.length > 7)
+                    break;
+            }
+            refuse(`"${term}" is a day-of-week range that wraps past Sunday, which the schedule cannot express. ` +
+                `List the days instead, for example "${days.join(",")}".`);
+        }
+        return `${from}-${to}`;
+    }
+    if (/^\d+$/.test(term))
+        return String(shiftDay(Number(term)));
+    // Day NAMES (MON, MON-FRI) mean the same thing in both syntaxes.
+    return term;
+}
+/**
+ * The smallest gap a recurring expression can produce, in seconds, or null
+ * when it is not a recognised rate()/cron() form. Mirrors hq-pro-agents
+ * `recurringIntervalSeconds` so the CLI can refuse a sub-floor schedule with
+ * the server's own reason instead of a round-trip and a raw 400.
+ */
+export function recurringIntervalSeconds(expr) {
+    const rate = expr.trim().match(/^rate\(\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*\)$/i);
+    if (rate) {
+        const n = Number(rate[1]);
+        if (!Number.isFinite(n) || n <= 0)
+            return null;
+        const unit = rate[2].toLowerCase();
+        if (unit.startsWith("minute"))
+            return n * 60;
+        if (unit.startsWith("hour"))
+            return n * 3600;
+        return n * 86400;
+    }
+    const cron = expr.trim().match(/^cron\(\s*(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s*\)$/i);
+    if (!cron)
+        return null;
+    const minute = cron[1];
+    if (minute === "*" || minute === "?")
+        return 60;
+    // EventBridge also writes a step as "start/every" ("0/10" = every 10 minutes
+    // from :00), which the rate()-style regex alone rejected as unparseable.
+    const step = minute.match(/^(?:\*|\d+|\d+-\d+)\/(\d+)$/);
+    if (step) {
+        const n = Number(step[1]);
+        return Number.isFinite(n) && n > 0 ? n * 60 : null;
+    }
+    if (/^\d+-\d+$/.test(minute))
+        return 60;
+    if (/^\d+(,\d+)*$/.test(minute)) {
+        const values = minute.split(",").map(Number).sort((a, b) => a - b);
+        if (values.some((v) => !Number.isFinite(v) || v < 0 || v > 59))
+            return null;
+        if (values.length === 1)
+            return 3600;
+        let smallest = 60 - values[values.length - 1] + values[0]; // wrap to the next hour
+        for (let i = 1; i < values.length; i += 1)
+            smallest = Math.min(smallest, values[i] - values[i - 1]);
+        return smallest * 60;
+    }
+    return null;
+}
+/** Refuse a schedule the cloud would refuse, with the cloud's own reason. */
+export function assertScheduleWithinFloor(expr) {
+    const interval = recurringIntervalSeconds(expr);
+    if (interval === null) {
+        refuse("schedule.cron must be a valid rate(...) or cron(...) expression");
+    }
+    if (interval < MIN_RECURRING_INTERVAL_SECONDS) {
+        refuse(`recurring jobs may not fire more often than every ${MIN_RECURRING_INTERVAL_SECONDS / 60} minutes`);
+    }
+}
+export function scheduleHelperPath(hqRoot) {
+    return path.join(hqRoot, "core", "scripts", "jobs-schedule-parse.sh");
+}
+/**
+ * Plain English → cron, using HQ's OWN helper (`core/scripts/jobs-schedule-parse.sh`)
+ * so `hq bot jobs --every` and the `/schedule` command agree on what "every
+ * weekday morning" means. When the helper is not in this HQ root, the caller is
+ * told to pass `--cron` instead rather than getting a second, divergent parser.
+ */
+export function parseScheduleText(text, opts) {
+    const helper = scheduleHelperPath(opts.hqRoot);
+    const exists = opts.exists ?? ((p) => fs.existsSync(p));
+    if (!exists(helper)) {
+        refuse(`I can't turn "${text}" into a schedule: HQ's schedule helper is not in this HQ folder ` +
+            `(${helper}). Pass the schedule directly instead, for example --cron "0 9 * * 1-5".`);
+    }
+    const exec = opts.exec ?? execFileSync;
+    let raw;
+    try {
+        raw = String(exec("bash", [helper, "--tz", opts.timezone, text], { encoding: "utf8" })).trim();
+    }
+    catch (err) {
+        const out = err.stdout;
+        raw = typeof out === "string" ? out.trim() : "";
+        if (!raw) {
+            refuse(`I couldn't work out a schedule from "${text}". Pass --cron "<expression>" instead.`);
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        refuse(`I couldn't work out a schedule from "${text}". Pass --cron "<expression>" instead.`);
+    }
+    if (!parsed.ok || !parsed.cron) {
+        refuse(`I couldn't work out a schedule from "${text}"${parsed.error ? ` (${parsed.error})` : ""}. Pass --cron "<expression>" instead.`);
+    }
+    return {
+        cron: parsed.cron,
+        timezone: parsed.timezone?.trim() || opts.timezone,
+        ...(parsed.human?.trim() ? { human: parsed.human.trim() } : {}),
+    };
+}
+/** The create body the cloud expects, with the client-side limits enforced first. */
+export function buildCreateJobBody(input) {
+    const prompt = input.prompt.trim();
+    if (!prompt)
+        refuse("Say what the job should do: --add \"<what to do>\".");
+    if (Buffer.byteLength(prompt, "utf-8") > MAX_PROMPT_BYTES) {
+        refuse(`That instruction is too long (${Buffer.byteLength(prompt, "utf-8")} bytes; the limit is ${MAX_PROMPT_BYTES}). ` +
+            `Shorten it, or put the detail in a file the bot reads when the job runs.`);
+    }
+    const cron = toEventBridgeCron(input.cron);
+    assertScheduleWithinFloor(cron);
+    return {
+        prompt,
+        ...(input.context ? { context: input.context } : {}),
+        schedule: { kind: "recurring", cron, timezone: input.timezone },
+    };
+}
+// ─── Reading jobs back ───────────────────────────────────────────────────────
+/** A schedule in plain words, falling back to the raw expression. */
+export function describeSchedule(job) {
+    const schedule = job.schedule;
+    if (!schedule)
+        return "on a schedule";
+    if (schedule.kind === "once")
+        return `once, at ${schedule.at ?? "an unknown time"}${schedule.timezone ? ` (${schedule.timezone})` : ""}`;
+    const expr = schedule.cron ?? "";
+    const zone = schedule.timezone ? ` (${schedule.timezone})` : "";
+    const words = cronInWords(expr);
+    return words ? `${words}${zone}` : `${expr}${zone}`;
+}
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** A small humaniser for the shapes `--every` actually produces. */
+export function cronInWords(expr) {
+    const rate = expr.trim().match(/^rate\(\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*\)$/i);
+    if (rate)
+        return `every ${rate[1]} ${rate[2].toLowerCase()}`;
+    const cron = expr.trim().match(/^cron\(\s*(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+\S+\s*\)$/i);
+    if (!cron)
+        return null;
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = [cron[1], cron[2], cron[3], cron[4], cron[5]];
+    const step = minute.match(/^(?:\*|\d+)\/(\d+)$/);
+    if (step && hour === "*")
+        return `every ${step[1]} minutes`;
+    const hourStep = hour.match(/^(?:\*|\d+)\/(\d+)$/);
+    if (/^\d+$/.test(minute) && hourStep)
+        return `every ${hourStep[1]} hours`;
+    if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour))
+        return null;
+    const at = `${String(Number(hour)).padStart(2, "0")}:${String(Number(minute)).padStart(2, "0")}`;
+    if (month !== "*")
+        return null;
+    if (dayOfWeek === "?" || dayOfWeek === "*") {
+        if (dayOfMonth === "*" || dayOfMonth === "?")
+            return `every day at ${at}`;
+        if (/^\d+$/.test(dayOfMonth))
+            return `on day ${dayOfMonth} of each month at ${at}`;
+        return null;
+    }
+    // EventBridge days of week: SUNDAY = 1.
+    if (dayOfWeek === "2-6")
+        return `every weekday at ${at}`;
+    if (/^\d$/.test(dayOfWeek))
+        return `every ${DAY_NAMES[(Number(dayOfWeek) + 6) % 7]} at ${at}`;
+    if (/^\d(,\d)+$/.test(dayOfWeek)) {
+        const days = dayOfWeek.split(",").map((d) => DAY_NAMES[(Number(d) + 6) % 7]);
+        return `every ${days.join(", ")} at ${at}`;
+    }
+    return null;
+}
+/** "never run yet" / "succeeded 2026-09-15 09:00 UTC". */
+export function describeLastRun(job) {
+    if (!job.lastStatus && !job.lastRunAt)
+        return "not run yet";
+    const when = job.lastRunAt ? ` ${job.lastRunAt.slice(0, 16).replace("T", " ")} UTC` : "";
+    return `${job.lastStatus ?? "ran"}${when}`;
+}
+export function formatJobsList(botName, jobs) {
+    if (jobs.length === 0) {
+        return `${botName} has no scheduled jobs. Add one with: hq bot jobs ${botName} --add "<what to do>" --every "<when>"`;
+    }
+    const lines = [`${botName} has ${jobs.length} scheduled job${jobs.length === 1 ? "" : "s"}:`];
+    for (const job of jobs) {
+        lines.push("");
+        lines.push(`  ${chalk.bold(job.jobId)}${job.status && job.status !== "active" ? chalk.yellow(` (${job.status})`) : ""}`);
+        lines.push(`    ${job.prompt.replace(/\s+/g, " ").slice(0, 120)}`);
+        lines.push(`    runs ${describeSchedule(job)}`);
+        lines.push(`    next run: ${job.nextRunAt ? `${job.nextRunAt.slice(0, 16).replace("T", " ")} UTC` : "not scheduled yet"}`);
+        lines.push(`    last run: ${describeLastRun(job)}`);
+    }
+    return lines.join("\n");
+}
+// ─── Errors a person can act on ──────────────────────────────────────────────
+/**
+ * Turn a jobs-route failure into one plain line.
+ *
+ * Personal bots are refused by the cloud today: their JWT carries the owner's
+ * `per_…` company claim and the jobs routes require a `cmp_…`, so the fail-closed
+ * guard answers 403 `CROSS_AGENT_JOB` (hq-pro-agents jobs/errors.ts
+ * `CrossAgentJobError`). That server fix is a separate change; until it lands the
+ * refusal must read as "not available yet for this kind of bot", not as a raw 403.
+ * Once the server accepts personal bots the refusal simply stops happening — no
+ * client change needed.
+ *
+ * ONLY that exact code is rewritten. Every other 403, and every 404, keeps its
+ * real message: masking them would hide a genuinely missing job or a different
+ * permission problem behind copy about the wrong thing.
+ */
+export function jobsErrorMessage(err, ctx) {
+    if (!(err instanceof BotApiError))
+        return err instanceof Error ? err.message : String(err);
+    if (ctx.kind === "personal" && err.status === 403 && err.code === "CROSS_AGENT_JOB") {
+        return (`Scheduled jobs aren't available for personal bots yet — the cloud only accepts them from ` +
+            `company bots. Create ${ctx.botName} as a company bot (hq bot create ${ctx.botName} --kind company ` +
+            `--company <slug>) to schedule work, or wait for personal-bot support.`);
+    }
+    if (err.status === 401)
+        return "Not authenticated — the bot's credentials were refused. Try: hq bot restart " + ctx.botName;
+    if (err.code === "JOB_QUOTA_EXCEEDED" || err.status === 409) {
+        return (`${ctx.botName} already has the maximum of ${MAX_ACTIVE_JOBS_PER_AGENT} scheduled jobs. ` +
+            `Remove one first: hq bot jobs ${ctx.botName} --rm <jobId>`);
+    }
+    if (err.status === 404 && err.code === "JOB_NOT_FOUND")
+        return `${ctx.botName} has no job with that id.`;
+    if (err.code === "INVALID_SCHEDULE" || err.code === "JOB_VALIDATION") {
+        return err.message.replace(/^HQ API [^:]+: /, "");
+    }
+    return err.message;
+}
+export async function runBotJobs(nameArg, opts, deps) {
+    const { name, dir, config } = deps.requireBot(nameArg);
+    const kind = effectiveBotKind(config);
+    const out = deps.out ?? ((line) => console.log(line));
+    const api = deps.apiFor
+        ? deps.apiFor(dir)
+        : new BotApi({ token: deps.botTokenSupplier(dir) });
+    const ctx = { botName: name, kind };
+    if (opts.add !== undefined && opts.rm !== undefined) {
+        refuse("Add a job or remove one, not both in the same command.");
+    }
+    if (opts.rm !== undefined) {
+        const jobId = opts.rm.trim();
+        if (!jobId)
+            refuse("Say which job to remove: --rm <jobId>");
+        try {
+            await api.cancelJob(config.agentUid, jobId);
+        }
+        catch (err) {
+            refuse(jobsErrorMessage(err, ctx));
+        }
+        out(opts.json ? JSON.stringify({ ok: true, removed: jobId }, null, 2) : chalk.green(`Removed ${jobId}. ${name} will not run it again.`));
+        return;
+    }
+    if (opts.add !== undefined) {
+        if (!opts.every && !opts.cron) {
+            refuse(`Say how often it should run: --every "every weekday at 9am", or --cron "0 9 * * 1-5".`);
+        }
+        if (opts.every && opts.cron)
+            refuse("Use --every or --cron, not both.");
+        const timezone = opts.tz?.trim() || (deps.timezone ?? machineTimezone)();
+        const parse = deps.parseSchedule ?? parseScheduleText;
+        const schedule = opts.every
+            ? parse(opts.every, { hqRoot: config.hqRoot, timezone })
+            : { cron: opts.cron, timezone };
+        const body = buildCreateJobBody({ prompt: opts.add, cron: schedule.cron, timezone: schedule.timezone });
+        let created;
+        try {
+            created = await api.createJob(config.agentUid, body);
+        }
+        catch (err) {
+            refuse(jobsErrorMessage(err, ctx));
+        }
+        if (opts.json) {
+            out(JSON.stringify({ ok: true, job: created }, null, 2));
+            return;
+        }
+        const words = ("human" in schedule && schedule.human) || describeSchedule(created);
+        out(chalk.green(`Scheduled ${created.jobId}: ${name} will ${body.prompt.replace(/\s+/g, " ").slice(0, 120)} — ${words}.`));
+        out(chalk.gray("If this computer is asleep or off when a run is due, it is picked up as a catch-up when the computer " +
+            "wakes, as long as it wakes within about an hour. After a longer outage that run is skipped and the " +
+            "job carries on at its next scheduled time."));
+        return;
+    }
+    let jobs;
+    try {
+        jobs = await api.listJobs(config.agentUid);
+    }
+    catch (err) {
+        refuse(jobsErrorMessage(err, ctx));
+    }
+    out(opts.json ? JSON.stringify(jobs, null, 2) : formatJobsList(name, jobs));
+}
+export function registerBotJobsCommand(bot, deps) {
+    bot
+        .command("jobs <name>")
+        .description("Show, schedule, or remove a bot's recurring jobs (the schedule runs in the cloud, not on this computer)")
+        .option("--add <what>", "Schedule new work, in plain language")
+        .option("--every <when>", 'How often, in plain language (e.g. "every weekday at 9am")')
+        .option("--cron <expr>", 'How often, as a cron expression (e.g. "0 9 * * 1-5")')
+        .option("--tz <zone>", "IANA timezone for the schedule (default: this computer's)")
+        .option("--rm <jobId>", "Remove a scheduled job")
+        .option("--json", "Print machine-readable JSON")
+        .action(async (name, opts) => {
+        try {
+            await runBotJobs(name, opts, deps);
+        }
+        catch (err) {
+            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=bot-jobs.js.map