@pimmesz/afterburner 1.0.10 → 1.0.12

package/dist/{chunk-Z3H5GIPM.js → chunk-4TD2KS3A.js}

@@ -148,6 +148,10 @@ var scheduleConfigSchema = z.object({
   cron: z.string().min(1).default("17 */4 * * *"),
   timezone: z.string().min(1).default("UTC")
 }).prefault({});
+var notifyConfigSchema = z.object({
+  /** Desktop banner per completed run, opt-in. The PR stays the primary signal. */
+  desktop: z.boolean().default(false)
+}).prefault({});
 var agentConfigSchema = z.object({
   backend: z.enum(["dry-run", "claude-code", "api-key"]).default("dry-run"),
   modelByCategory: z.partialRecord(categoryEnum, modelId).default({}).transform((m) => ({ ...DEFAULT_MODEL_BY_CATEGORY, ...m })),
@@ -174,6 +178,7 @@ var configSchema = z.object({
   budget: budgetConfigSchema,
   schedule: scheduleConfigSchema,
   agent: agentConfigSchema,
+  notify: notifyConfigSchema,
   taskCategories: taskCategoriesConfigSchema
 }).superRefine((config, ctx) => {
   for (const [category, model] of Object.entries(config.agent.modelByCategory)) {
@@ -693,6 +698,85 @@ function systemdQuote(value) {
   return /[\s"']/.test(value) ? `"${value.replaceAll('"', '\\"')}"` : value;
 }
 
+// src/core/notify/desktop.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var run = promisify(execFile);
+var EXEC_TIMEOUT_MS = 1e4;
+var DesktopNotifier = class {
+  exec;
+  has;
+  platform;
+  constructor(deps = {}) {
+    this.exec = deps.exec ?? ((command, args, opts) => run(command, args, { timeout: EXEC_TIMEOUT_MS, ...opts }));
+    this.has = deps.has ?? commandExists;
+    this.platform = deps.platform ?? process.platform;
+  }
+  async notify(record) {
+    const title = "Afterburner";
+    const subtitle = `${shortRepo(record.repoUrl)} \xB7 ${record.outcome}`;
+    const body = record.title;
+    try {
+      switch (this.platform) {
+        case "darwin":
+          await this.notifyMac(title, subtitle, body, record.prUrl);
+          break;
+        case "linux":
+          await this.notifyLinux(title, `${subtitle} \u2014 ${body}`);
+          break;
+        case "win32":
+          await this.notifyWindows(title, `${subtitle} \u2014 ${body}`);
+          break;
+      }
+    } catch {
+    }
+  }
+  async notifyMac(title, subtitle, body, prUrl) {
+    if (await this.has("terminal-notifier")) {
+      const args = ["-title", title, "-subtitle", subtitle, "-message", body, "-sound", "default"];
+      if (prUrl) args.push("-open", prUrl);
+      await this.exec("terminal-notifier", args);
+      return;
+    }
+    const script = 'display notification (system attribute "AB_BODY") with title (system attribute "AB_TITLE") subtitle (system attribute "AB_SUBTITLE")';
+    await this.exec("osascript", ["-e", script], {
+      env: { ...process.env, AB_TITLE: title, AB_SUBTITLE: subtitle, AB_BODY: body }
+    });
+  }
+  async notifyLinux(title, body) {
+    await this.exec("notify-send", ["--app-name=afterburner", "--", title, body]);
+  }
+  async notifyWindows(title, body) {
+    const aumid = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe";
+    const script = [
+      "[Windows.UI.Notifications.ToastNotificationManager,Windows.UI.Notifications,ContentType=WindowsRuntime]>$null",
+      "[Windows.Data.Xml.Dom.XmlDocument,Windows.Data.Xml.Dom,ContentType=WindowsRuntime]>$null",
+      "$t=[System.Security.SecurityElement]::Escape($env:AB_TITLE)",
+      "$b=[System.Security.SecurityElement]::Escape($env:AB_BODY)",
+      '$x="<toast><visual><binding template=`"ToastGeneric`"><text>$t</text><text>$b</text></binding></visual></toast>"',
+      "$d=[Windows.Data.Xml.Dom.XmlDocument]::new();$d.LoadXml($x)",
+      `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${aumid}').Show([Windows.UI.Notifications.ToastNotification]::new($d))`
+    ].join(";");
+    await this.exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+      env: { ...process.env, AB_TITLE: title, AB_BODY: body }
+    });
+  }
+};
+function shortRepo(repoUrl) {
+  const trimmed = repoUrl.replace(/[/\\]+$/, "");
+  const last = trimmed.split(/[/\\]/).pop() ?? trimmed;
+  return last.replace(/\.git$/, "") || trimmed;
+}
+async function commandExists(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  try {
+    await run(finder, [command]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/core/store/run-store.ts
 import { appendFile, mkdir as mkdir2, readFile as readFile3 } from "fs/promises";
 import { dirname as dirname2 } from "path";
@@ -734,6 +818,26 @@ var ConsoleNotifier = class {
   }
 };
 
+// src/core/notify/factory.ts
+var CompositeNotifier = class {
+  constructor(notifiers) {
+    this.notifiers = notifiers;
+  }
+  notifiers;
+  async notify(record) {
+    for (const notifier of this.notifiers) {
+      try {
+        await notifier.notify(record);
+      } catch {
+      }
+    }
+  }
+};
+function createNotifier(config) {
+  const consoleNotifier = new ConsoleNotifier();
+  return config.notify.desktop ? new CompositeNotifier([consoleNotifier, new DesktopNotifier()]) : consoleNotifier;
+}
+
 // src/core/orchestrator.ts
 async function runOnce(deps) {
   const { config } = deps;
@@ -1115,8 +1219,12 @@ export {
   scheduleArtifactPaths,
   generateScheduleArtifacts,
   looksRemoteRepoUrl,
+  DesktopNotifier,
+  commandExists,
   JsonlRunStore,
   ConsoleNotifier,
+  CompositeNotifier,
+  createNotifier,
   runOnce,
   ApiKeyRunner,
   taskFingerprint,

package/dist/cli/index.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import {
-  ConsoleNotifier,
   JsonlRunStore,
   ManualBudgetProvider,
   budgetFromUsageCache,
   claudeConfigDir,
+  commandExists,
   createBudgetProvider,
+  createNotifier,
   createRunner,
   createSelector,
   dataDir,
@@ -24,7 +25,7 @@ import {
   shouldIgnite,
   startWatch,
   writeUsageCache
-} from "../chunk-Z3H5GIPM.js";
+} from "../chunk-4TD2KS3A.js";
 import {
   MCP_STUB_MESSAGE
 } from "../chunk-2NSOEZWY.js";
@@ -35,7 +36,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@pimmesz/afterburner",
-  version: "1.0.10",
+  version: "1.0.12",
   description: "Convert idle Claude subscription quota into shippable engineering work: budget-aware trigger, bounded task selection, PR-only output.",
   license: "Apache-2.0",
   publishConfig: {
@@ -277,9 +278,9 @@ function resolveCliEntry() {
 
 // src/cli/commands/doctor.ts
 function registerDoctor(program2, packageInfo2) {
-  program2.command("doctor").description("Check prerequisites and configuration; every failure prints an actionable fix").option("--config <path>", "path to a config file").option("--check-updates", "query the npm registry for the latest published version").action(
-    (opts) => runDoctor({ packageInfo: packageInfo2, configPath: opts.config, checkUpdates: opts.checkUpdates })
-  );
+  program2.command("doctor").description("Check prerequisites and configuration; every failure prints an actionable fix").option("--config <path>", "path to a config file").option("--check-updates", "query the npm registry for the latest published version").action(async (opts) => {
+    await runDoctor({ packageInfo: packageInfo2, configPath: opts.config, checkUpdates: opts.checkUpdates });
+  });
 }
 async function runDoctor(opts) {
   console.log(`${deco(emoji.fuel)}${bold("afterburner doctor")}`);
@@ -325,6 +326,7 @@ async function runDoctor(opts) {
     results.push(checkRepos(config, configPath));
     results.push(...checkBackend(config));
     results.push(await checkBudgetProvider(config));
+    if (config.notify.desktop) results.push(checkNotify());
   }
   results.push(await checkRunStoreWritable());
   let failures = 0;
@@ -358,6 +360,7 @@ ${renderDoctorNextSteps({
     })}`
   );
   process.exitCode = failures === 0 ? 0 : 1;
+  return { ok: failures === 0, config, configPath };
 }
 async function buildRunSummary(config) {
   let budget = null;
@@ -392,7 +395,7 @@ function renderRunSummary(opts) {
   const what = categories.length === 0 ? `Would review ${repoLabel}, but every repo task category is switched off in taskCategories` : `Reviews ${repoLabel} for ${categories.join("/")} tasks`;
   let why;
   if (!budget) {
-    why = `Based on ${config.budget.provider}: no numbers available right now, so a run would refuse to start.`;
+    why = `${config.budget.provider} \u2014 no numbers available right now, so a run would refuse to start.`;
   } else {
     const gateConfig = {
       minWeeklyHeadroomPct: config.budget.minWeeklyHeadroomPct,
@@ -403,22 +406,21 @@ function renderRunSummary(opts) {
     const anySize = fullSize.go ? fullSize : shouldIgnite(budget, 0, gateConfig);
     const verdict = fullSize.go ? "the budget gate would let a run through right now" : anySize.go ? `a task at the ${formatTokens(config.agent.maxTaskTokens)}-token cap would not fit right now, though cheaper tasks still could` : `the budget gate would block any run right now (${fullSize.reason})`;
     const usage = `${Math.round(budget.weeklyRemainingPct)}% of the weekly quota left (~${formatTokens(Math.round(budget.weeklyRemainingTokensEst))} tokens), 5-hour session ${budget.sessionAvailable ? "available" : "exhausted"}`;
-    why = `Based on ${config.budget.provider}: ${usage} \u2192 ${verdict}.`;
+    why = `${config.budget.provider} \u2014 ${usage} \u2192 ${verdict}.`;
   }
-  return `${section(emoji.thrust, "Summary")}
-  ${what} \u2014 at most one PR per run, up to ${formatTokens(config.agent.maxTaskTokens)} tokens.
-  ${renderWhen(opts)}
-  ${why}`;
+  return `  What:   ${what} \u2014 at most one PR per run, up to ${formatTokens(config.agent.maxTaskTokens)} tokens.
+  When:   ${renderWhen(opts)}
+  Budget: ${why}`;
 }
 function renderWhen(opts) {
   const { config } = opts;
   const cron = config.schedule.cron;
   const cadence = describeCadence(cron);
   if (opts.scheduleInstalled === false) {
-    return `When: no afterburner schedule is installed \u2014 it only runs when you start it; \`afterburner schedule install\` would run it ${cadence}.`;
+    return `no afterburner schedule is installed \u2014 it only runs when you start it; \`afterburner schedule install\` would run it ${cadence} ${config.schedule.timezone}.`;
   }
   if (opts.scheduleInstalled === "unknown") {
-    return `When: ${cadence}, once the entries from \`afterburner schedule install\` are active (not auto-detectable on this platform).`;
+    return `${cadence} ${config.schedule.timezone}, once the entries from \`afterburner schedule install\` are active (not auto-detectable on this platform).`;
   }
   const zone = opts.scheduleKind === "systemd-user" ? config.schedule.timezone : opts.systemTimezone;
   const kindLabel = opts.scheduleKind === "systemd-user" ? "systemd" : "launchd";
@@ -434,9 +436,9 @@ function renderWhen(opts) {
       minute: "2-digit",
       hourCycle: "h23"
     }).format(next);
-    return `When: next run ${formatted} (${zone}), then ${cadence} \u2014 via the installed ${kindLabel} entry, if activated and in sync with this config${zoneNote}.`;
+    return `next run ${formatted} (${zone}), then ${cadence} \u2014 via the installed ${kindLabel} entry, if activated and in sync with this config${zoneNote}.`;
   } catch {
-    return `When: an installed ${kindLabel} entry runs it on cron '${cron}' (${zone}), if activated.`;
+    return `an installed ${kindLabel} entry runs it on cron '${cron}' (${zone}), if activated.`;
   }
 }
 function describeCadence(cron) {
@@ -447,12 +449,12 @@ function describeCadence(cron) {
   } catch {
     return `on cron '${cron}'`;
   }
-  if (hours.length === 24) return `every hour at minute ${minute}`;
-  const step2 = (hours[1] ?? 0) - (hours[0] ?? 0);
-  const uniform = hours.length > 1 && hours[0] === 0 && 24 % step2 === 0 && hours.length === 24 / step2 && hours.every((h, i) => h === i * step2);
-  if (uniform) return `every ${step2} hours at minute ${minute}`;
   const mm = String(minute).padStart(2, "0");
+  if (hours.length === 24) return `every hour at :${mm}`;
   const times = hours.map((h) => `${String(h).padStart(2, "0")}:${mm}`);
+  const step2 = (hours[1] ?? 0) - (hours[0] ?? 0);
+  const uniform = hours.length > 1 && hours[0] === 0 && 24 % step2 === 0 && hours.length === 24 / step2 && hours.every((h, i) => h === i * step2);
+  if (uniform) return `every ${step2} hours, at ${times.join(", ")}`;
   return `daily at ${times.join(", ")}`;
 }
 function renderDoctorNextSteps(opts) {
@@ -484,6 +486,17 @@ ${nextCmd(cmd("doctor"))}`;
   const engineLine = config.agent.backend === "dry-run" ? "dry-run \u2014 simulation only; set agent.backend: 'claude-code' in the config to do real work" : config.agent.backend === "claude-code" ? "claude-code \u2014 spends subscription quota you already pay for; PRs only with --live" : "api-key \u2014 bills your Anthropic API account per token (real money); PRs only with --live";
   const budgetLine = config.budget.provider === "manual" ? "manual \u2014 trusts budget.manual (automatic option: `afterburner statusline install`, then budget.provider: 'claude-usage')" : config.budget.provider === "claude-usage" ? "claude-usage \u2014 reads your real usage via the status line hook" : "claude-code-transcripts \u2014 estimates from local Claude Code session logs";
   const nextNote = config.agent.backend === "dry-run" ? "previews the next task; nothing is executed or spent" : `previews the next task (live execution ships in a future release; ${cmd("run-once --live")} currently validates and refuses)`;
+  const stopLine = `\`afterburner schedule uninstall\` (or Ctrl-C for watch); ${cmd("log")} lists every past run`;
+  if (opts.summary) {
+    return `${section(emoji.flame, "Ready")}
+  Config: ${configPath}
+${opts.summary}
+  Engine: ${engineLine}
+  Stop:   ${stopLine}
+
+${next}
+${nextCmd(cmd("run-once --dry-run"), nextNote)}`;
+  }
   const headroomClause = `weekly headroom drops below ${config.budget.minWeeklyHeadroomPct}%`;
   const gateLine = config.budget.requireSessionAvailable ? `runs skip themselves when no 5-hour session window is free or ${headroomClause}` : `runs skip themselves when ${headroomClause}`;
   return `${section(emoji.flame, "Ready")}
@@ -495,11 +508,9 @@ ${nextCmd(cmd("doctor"))}`;
   Gate:   ${gateLine}
   Safety: live PRs need BOTH a live engine in the config AND --live (two-part opt-in)
   Runs:   only when you start them \u2014 \`afterburner schedule install\` (recommended OS scheduler; cron '${config.schedule.cron}' ${config.schedule.timezone}) or \`afterburner watch\` (foreground) make it recurring
-  Stop:   \`afterburner schedule uninstall\` (or Ctrl-C for watch); ${cmd("log")} lists every past run
+  Stop:   ${stopLine}
 
-${opts.summary ? `${opts.summary}
-
-` : ""}${next}
+${next}
 ${nextCmd(cmd("run-once --dry-run"), nextNote)}`;
 }
 function checkVersion(opts) {
@@ -743,6 +754,42 @@ function formatAge(ms) {
   if (minutes < 60) return `${minutes}m`;
   return `${Math.round(minutes / 60)}h`;
 }
+function checkNotify(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const has = deps.has ?? commandExistsSync;
+  if (platform === "darwin") {
+    return has("terminal-notifier") ? {
+      name: "notify",
+      ok: true,
+      detail: "desktop banners via terminal-notifier (clickable PR links)"
+    } : {
+      name: "notify",
+      ok: true,
+      detail: "desktop banners via osascript (banners only, not clickable); `brew install terminal-notifier` adds clickable PR links"
+    };
+  }
+  if (platform === "linux") {
+    return has("notify-send") ? { name: "notify", ok: true, detail: "desktop banners via notify-send" } : {
+      name: "notify",
+      ok: false,
+      detail: "desktop notifications enabled but notify-send is not on PATH",
+      fix: "Install libnotify (Debian/Ubuntu: `apt install libnotify-bin`, Fedora: `dnf install libnotify`), or set notify.desktop: false."
+    };
+  }
+  if (platform === "win32") {
+    return { name: "notify", ok: true, detail: "desktop banners via PowerShell toast" };
+  }
+  return {
+    name: "notify",
+    ok: false,
+    detail: `desktop notifications enabled but no native backend exists on ${platform}`,
+    fix: "Set notify.desktop: false; this platform has no desktop banner support."
+  };
+}
+function commandExistsSync(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  return spawnSync(finder, [command], { stdio: "ignore" }).status === 0;
+}
 function classifyClaudeAuth(exitStatus, stdout) {
   if (exitStatus !== 0) {
     return {
@@ -790,11 +837,91 @@ async function checkRunStoreWritable() {
 }
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync3, statSync as statSync2 } from "fs";
-import { writeFile as writeFile2 } from "fs/promises";
+import { spawn } from "child_process";
+import { existsSync as existsSync4, statSync as statSync2 } from "fs";
+import { writeFile as writeFile3 } from "fs/promises";
 import { createInterface } from "readline/promises";
 import { homedir } from "os";
-import { join as join2, resolve as resolve3 } from "path";
+import { join as join2, resolve as resolve4 } from "path";
+
+// src/cli/commands/schedule.ts
+import { mkdir as mkdir2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { dirname as dirname2, resolve as resolve3 } from "path";
+function currentPlatform() {
+  const platform = process.platform;
+  if (platform === "darwin" || platform === "linux" || platform === "win32") return platform;
+  fail(
+    `Unsupported platform "${platform}" for native scheduling. Use \`afterburner watch\` instead.`
+  );
+}
+async function performScheduleInstall(platform, configPath, config) {
+  const artifacts = generateScheduleArtifacts(platform, {
+    cron: config.schedule.cron,
+    timezone: config.schedule.timezone,
+    nodePath: process.execPath,
+    cliPath: resolveCliEntry(),
+    configPath
+  });
+  const written = [];
+  for (const file of artifacts.files) {
+    await mkdir2(dirname2(file.path), { recursive: true });
+    await writeFile2(file.path, file.content, "utf8");
+    written.push(file.path);
+  }
+  return {
+    kind: artifacts.kind,
+    written,
+    activationHint: artifacts.activationHint,
+    removalHint: artifacts.removalHint
+  };
+}
+function registerSchedule(program2) {
+  const schedule = program2.command("schedule").description("Install or remove a native OS scheduler entry (launchd / systemd / schtasks)");
+  schedule.command("install").description("Generate and install the native scheduler entry for this OS").option("--config <path>", "path to a config file (recorded in the scheduled command)").action(async (opts) => {
+    const { config, filepath } = await loadConfigOrExit(opts.config);
+    const configPath = opts.config ? resolve3(opts.config) : filepath;
+    const result = await performScheduleInstall(currentPlatform(), configPath, config);
+    for (const path of result.written) console.log(`Wrote ${path}`);
+    console.log(`
+Kind: ${result.kind}`);
+    console.log(`Scheduled runs will use this config: ${configPath}`);
+    console.log(`Activate with:
+${result.activationHint}`);
+    console.log(`
+Remove later with:
+${result.removalHint}`);
+  });
+  schedule.command("uninstall").description("Remove the native scheduler entry files for this OS").option("--config <path>", "path to a config file").action(async (opts) => {
+    const { config } = await loadConfigOrExit(opts.config);
+    const artifacts = generateScheduleArtifacts(currentPlatform(), {
+      cron: config.schedule.cron,
+      timezone: config.schedule.timezone,
+      nodePath: process.execPath,
+      cliPath: resolveCliEntry()
+    });
+    if (artifacts.files.length === 0) {
+      console.log(
+        `Nothing to delete on this platform. Remove the tasks with:
+${artifacts.removalHint}`
+      );
+      return;
+    }
+    for (const file of artifacts.files) {
+      if (existsSync3(file.path)) {
+        await rm2(file.path);
+        console.log(`Removed ${file.path}`);
+      } else {
+        console.log(`Not found (already removed?): ${file.path}`);
+      }
+    }
+    console.log(`
+Finish deactivation with:
+${artifacts.removalHint}`);
+  });
+}
+
+// src/cli/commands/init.ts
 var BACKENDS = ["dry-run", "claude-code", "api-key"];
 var BUDGET_PROVIDERS = ["manual", "claude-usage", "claude-code-transcripts"];
 var ENGINE_CHOICES = {
@@ -855,12 +982,18 @@ async function runInit(opts, packageInfo2) {
   }
   const { backend, budgetProvider, repoUrl, verifyNow, targetDir, target } = answers;
   assertCanWriteConfig(targetDir, target, opts.force === true || answers.overwriteConsented);
-  await writeFile2(target, renderConfig(backend, budgetProvider, repoUrl), "utf8");
+  await writeFile3(target, renderConfig(backend, budgetProvider, repoUrl), "utf8");
   console.log(`
 ${step("Config", target)}`);
   if (verifyNow) {
     console.log();
-    await runDoctor({ packageInfo: packageInfo2, configPath: target });
+    const { ok, config, configPath } = await runDoctor({ packageInfo: packageInfo2, configPath: target });
+    if (!opts.yes && ok && config && configPath) {
+      await offerScheduleInstall(configPath, config);
+      if (await offerDesktopNotifications()) {
+        await writeFile3(target, renderConfig(backend, budgetProvider, repoUrl, true), "utf8");
+      }
+    }
     return;
   }
   console.log(
@@ -874,6 +1007,118 @@ ${renderOnboardingSummary({
     })}`
   );
 }
+async function offerScheduleInstall(configPath, config, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "linux" && platform !== "win32") {
+    return false;
+  }
+  const created = deps.rl ? null : createInterface({ input: process.stdin, output: process.stdout });
+  created?.on("SIGINT", () => created.close());
+  const rl = deps.rl ?? created;
+  try {
+    const answer = (await rl.question("\nInstall the schedule now, so it runs unattended? [y/N]: ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      console.log(
+        dim("Skipped \u2014 run `afterburner schedule install` whenever you want it recurring.")
+      );
+      return false;
+    }
+    const install2 = deps.install ?? performScheduleInstall;
+    const result = await install2(platform, configPath, config);
+    for (const path of result.written) console.log(`  ${green("\u2713")} wrote ${path}`);
+    console.log(
+      `
+${bold("One more step \u2014 turn it on")} (the entry is written but not yet active):
+  ${result.activationHint}`
+    );
+    console.log(dim("\nStop it later with `afterburner schedule uninstall`."));
+    return true;
+  } catch (error) {
+    if (error?.code === "ABORT_ERR") {
+      console.log(dim("\nSkipped scheduling."));
+      return false;
+    }
+    console.log(
+      errYellow(
+        `Could not install a native schedule: ${error instanceof Error ? error.message : String(error)}. Run \`afterburner schedule install\` later, or use \`afterburner watch\`.`
+      )
+    );
+    return false;
+  } finally {
+    created?.close();
+  }
+}
+async function offerDesktopNotifications(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const created = deps.rl ? null : createInterface({ input: process.stdin, output: process.stdout });
+  created?.on("SIGINT", () => created.close());
+  const rl = deps.rl ?? created;
+  try {
+    const answer = (await rl.question("\nSend a desktop notification when a run completes? [y/N]: ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      console.log(dim("Skipped \u2014 set notify.desktop: true in the config to enable later."));
+      return false;
+    }
+    const has = deps.has ?? commandExists;
+    if (platform === "darwin") {
+      if (!await has("terminal-notifier") && await has("brew")) {
+        const sub = (await rl.question(
+          "Install terminal-notifier for clickable banners (brew install terminal-notifier)? [y/N]: "
+        )).trim().toLowerCase();
+        if (sub === "y" || sub === "yes") {
+          try {
+            console.log(dim("Installing terminal-notifier\u2026"));
+            await (deps.install ?? brewInstall)("terminal-notifier");
+            console.log(`  ${green("\u2713")} installed terminal-notifier`);
+          } catch (error) {
+            console.log(
+              errYellow(
+                `Could not install terminal-notifier: ${error instanceof Error ? error.message : String(error)}. Banners will use osascript (no click) until you install it.`
+              )
+            );
+          }
+        }
+      }
+    }
+    const backendReady = platform === "darwin" || platform === "win32" ? true : platform === "linux" ? await has("notify-send") : false;
+    if (backendReady) {
+      console.log(dim("Desktop notifications on \u2014 a banner fires when a run completes."));
+    } else if (platform === "linux") {
+      console.log(
+        errYellow(
+          "Desktop notifications enabled, but notify-send is not on PATH \u2014 install libnotify (Debian/Ubuntu: `apt install libnotify-bin`) for banners to appear."
+        )
+      );
+    } else {
+      console.log(
+        errYellow(
+          `Desktop notifications enabled, but ${platform} has no desktop banner backend; runs still log to the console and run store.`
+        )
+      );
+    }
+    return true;
+  } catch (error) {
+    if (error?.code === "ABORT_ERR") return false;
+    console.log(
+      errYellow(
+        `Could not set up notifications: ${error instanceof Error ? error.message : String(error)}.`
+      )
+    );
+    return false;
+  } finally {
+    created?.close();
+  }
+}
+function brewInstall(formula) {
+  return new Promise((resolve7, reject) => {
+    const child = spawn("brew", ["install", formula], { stdio: "inherit" });
+    child.on("error", reject);
+    child.on(
+      "close",
+      (code) => code === 0 ? resolve7() : reject(new Error(`brew install exited with code ${code}`))
+    );
+  });
+}
 async function collectAnswers(rl, opts, cwd = process.cwd()) {
   let targetDir = cwd;
   let target = join2(targetDir, "afterburner.config.mjs");
@@ -888,7 +1133,7 @@ async function collectAnswers(rl, opts, cwd = process.cwd()) {
   console.log(step("Engine", backend));
   console.log(`
 ${bold("Step 2 of 3 \u2014 Repository (the allowlist of what it may touch)")}`);
-  const detectedRepo = existsSync3(join2(cwd, ".git")) ? cwd : null;
+  const detectedRepo = existsSync4(join2(cwd, ".git")) ? cwd : null;
   if (detectedRepo) {
     console.log(`  - press Enter to use this folder (a git repo): ${detectedRepo}`);
   }
@@ -957,7 +1202,7 @@ function assertCanWriteConfig(targetDir, target, force) {
 }
 function configConflict(targetDir, target) {
   const existing = CONFIG_FILENAMES.map((name) => join2(targetDir, name)).filter(
-    (p) => existsSync3(p)
+    (p) => existsSync4(p)
   );
   return {
     exact: existing.includes(target) ? target : null,
@@ -978,7 +1223,7 @@ Overwrite it with these new answers? Only this file changes \u2014 your repo is
   return answer === "y" || answer === "yes";
 }
 function hasConfig(dir) {
-  return CONFIG_FILENAMES.some((name) => existsSync3(join2(dir, name)));
+  return CONFIG_FILENAMES.some((name) => existsSync4(join2(dir, name)));
 }
 async function askChoice(rl, prompt, count) {
   for (; ; ) {
@@ -991,7 +1236,7 @@ async function askChoice(rl, prompt, count) {
 function localRepoPath(repoUrl, base = process.cwd()) {
   if (repoUrl === "" || looksRemoteRepoUrl(repoUrl)) return null;
   const expanded = repoUrl === "~" ? homedir() : repoUrl.replace(/^~(?=\/)/, homedir());
-  const absolute = resolve3(base, expanded);
+  const absolute = resolve4(base, expanded);
   return statSync2(absolute, { throwIfNoEntry: false })?.isDirectory() ? absolute : null;
 }
 function renderOnboardingSummary(opts) {
@@ -1017,7 +1262,7 @@ function renderOnboardingSummary(opts) {
   );
   return lines.join("\n");
 }
-function renderConfig(backend, budgetProvider, repoUrl) {
+function renderConfig(backend, budgetProvider, repoUrl, desktopNotify = false) {
   const repoBlock = repoUrl ? `    {
       url: ${JSON.stringify(repoUrl)},
       defaultBranch: 'main',
@@ -1067,6 +1312,11 @@ ${repoBlock}
     // money at API rates outside promotional windows.
     allowFable: false,
   },
+  notify: {
+    // Desktop banner when a run completes (macOS/Linux/Windows). The opened PR
+    // is still the primary notification; this is a local convenience.
+    desktop: ${desktopNotify},
+  },
 };
 
 export default config;
@@ -1166,7 +1416,7 @@ function registerRunOnce(program2) {
       selector: createSelector(config),
       runner,
       store: new JsonlRunStore(),
-      notifier: new ConsoleNotifier()
+      notifier: createNotifier(config)
     });
     if (outcomes.some((o) => o.status === "completed")) await ignite();
     for (const outcome of outcomes) {
@@ -1199,72 +1449,6 @@ ${section(emoji.rocket, "Next")}`);
   });
 }
 
-// src/cli/commands/schedule.ts
-import { mkdir as mkdir2, rm as rm2, writeFile as writeFile3 } from "fs/promises";
-import { existsSync as existsSync4 } from "fs";
-import { dirname as dirname2, resolve as resolve4 } from "path";
-function currentPlatform() {
-  const platform = process.platform;
-  if (platform === "darwin" || platform === "linux" || platform === "win32") return platform;
-  fail(
-    `Unsupported platform "${platform}" for native scheduling. Use \`afterburner watch\` instead.`
-  );
-}
-function registerSchedule(program2) {
-  const schedule = program2.command("schedule").description("Install or remove a native OS scheduler entry (launchd / systemd / schtasks)");
-  schedule.command("install").description("Generate and install the native scheduler entry for this OS").option("--config <path>", "path to a config file (recorded in the scheduled command)").action(async (opts) => {
-    const { config, filepath } = await loadConfigOrExit(opts.config);
-    const configPath = opts.config ? resolve4(opts.config) : filepath;
-    const artifacts = generateScheduleArtifacts(currentPlatform(), {
-      cron: config.schedule.cron,
-      timezone: config.schedule.timezone,
-      nodePath: process.execPath,
-      cliPath: resolveCliEntry(),
-      configPath
-    });
-    for (const file of artifacts.files) {
-      await mkdir2(dirname2(file.path), { recursive: true });
-      await writeFile3(file.path, file.content, "utf8");
-      console.log(`Wrote ${file.path}`);
-    }
-    console.log(`
-Kind: ${artifacts.kind}`);
-    console.log(`Scheduled runs will use this config: ${configPath}`);
-    console.log(`Activate with:
-${artifacts.activationHint}`);
-    console.log(`
-Remove later with:
-${artifacts.removalHint}`);
-  });
-  schedule.command("uninstall").description("Remove the native scheduler entry files for this OS").option("--config <path>", "path to a config file").action(async (opts) => {
-    const { config } = await loadConfigOrExit(opts.config);
-    const artifacts = generateScheduleArtifacts(currentPlatform(), {
-      cron: config.schedule.cron,
-      timezone: config.schedule.timezone,
-      nodePath: process.execPath,
-      cliPath: resolveCliEntry()
-    });
-    if (artifacts.files.length === 0) {
-      console.log(
-        `Nothing to delete on this platform. Remove the tasks with:
-${artifacts.removalHint}`
-      );
-      return;
-    }
-    for (const file of artifacts.files) {
-      if (existsSync4(file.path)) {
-        await rm2(file.path);
-        console.log(`Removed ${file.path}`);
-      } else {
-        console.log(`Not found (already removed?): ${file.path}`);
-      }
-    }
-    console.log(`
-Finish deactivation with:
-${artifacts.removalHint}`);
-  });
-}
-
 // src/cli/commands/skill.ts
 import { copyFile, mkdir as mkdir3 } from "fs/promises";
 import { existsSync as existsSync5 } from "fs";
@@ -1294,7 +1478,7 @@ function registerSkill(program2) {
 }
 
 // src/cli/commands/statusline.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync6 } from "fs";
 import { copyFile as copyFile2, mkdir as mkdir4, readFile, rm as rm3, writeFile as writeFile4 } from "fs/promises";
 import { dirname as dirname3, join as join4 } from "path";
@@ -1369,7 +1553,7 @@ async function readWrappedState() {
 }
 function passThrough(command, input) {
   return new Promise((resolve7) => {
-    const child = spawn(command, { shell: true, stdio: ["pipe", "inherit", "inherit"] });
+    const child = spawn2(command, { shell: true, stdio: ["pipe", "inherit", "inherit"] });
     child.on("error", () => resolve7());
     child.on("close", () => resolve7());
     child.stdin.on("error", () => {
@@ -1689,7 +1873,7 @@ function registerWatch(program2) {
           selector: createSelector(config),
           runner,
           store: new JsonlRunStore(),
-          notifier: new ConsoleNotifier()
+          notifier: createNotifier(config)
         });
         for (const outcome of outcomes) {
           console.log(`[afterburner]   ${outcome.repoUrl}: ${outcome.status}, ${outcome.reason}`);

package/dist/core/index.d.ts

@@ -53,8 +53,8 @@ declare const budgetConfigSchema: z.ZodPrefault<z.ZodObject<{
 }, z.core.$strip>>;
 declare const agentConfigSchema: z.ZodPrefault<z.ZodObject<{
     backend: z.ZodDefault<z.ZodEnum<{
-        "claude-code": "claude-code";
         "dry-run": "dry-run";
+        "claude-code": "claude-code";
         "api-key": "api-key";
     }>>;
     modelByCategory: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
@@ -115,8 +115,8 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strip>>;
     agent: z.ZodPrefault<z.ZodObject<{
         backend: z.ZodDefault<z.ZodEnum<{
-            "claude-code": "claude-code";
             "dry-run": "dry-run";
+            "claude-code": "claude-code";
             "api-key": "api-key";
         }>>;
         modelByCategory: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
@@ -139,6 +139,9 @@ declare const configSchema: z.ZodObject<{
         maxTaskTokens: z.ZodDefault<z.ZodNumber>;
         allowFable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    notify: z.ZodPrefault<z.ZodObject<{
+        desktop: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     taskCategories: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
         security: "security";
         tests: "tests";
@@ -683,6 +686,58 @@ declare class ConsoleNotifier implements Notifier {
     notify(record: RunRecord): Promise<void>;
 }
 
+/** Spawn options we actually use; kept narrow so the injected exec is easy to fake. */
+interface ExecOpts {
+    env?: NodeJS.ProcessEnv;
+}
+type Exec = (command: string, args: string[], opts?: ExecOpts) => Promise<unknown>;
+interface DesktopNotifierDeps {
+    /** Spawns a command (argv array, never a shell string). Injected in tests. */
+    exec?: Exec;
+    /** Whether a binary is resolvable on PATH. Injected in tests. */
+    has?: (command: string) => Promise<boolean>;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Fires an OS-native desktop banner per completed run, with zero npm
+ * dependencies — it shells out to platform tools: terminal-notifier (clickable)
+ * or osascript on macOS, notify-send on Linux, a PowerShell toast on Windows.
+ *
+ * Two invariants:
+ * 1. Untrusted record text (title, repo) is passed as argv or via environment
+ *    variables, NEVER interpolated into a shell string or a second interpreter's
+ *    source. osascript evaluates AppleScript and PowerShell evaluates a script,
+ *    so their dynamic text comes from env (`system attribute` / `$env:`), which
+ *    closes the AppleScript/script-injection hole an argv array alone leaves open.
+ * 2. notify() never throws: a missing tool, denied permission, or headless box
+ *    must not break a run. The run store stays the source of truth.
+ */
+declare class DesktopNotifier implements Notifier {
+    private readonly exec;
+    private readonly has;
+    private readonly platform;
+    constructor(deps?: DesktopNotifierDeps);
+    notify(record: RunRecord): Promise<void>;
+    private notifyMac;
+    private notifyLinux;
+    private notifyWindows;
+}
+/** True when `command` resolves on PATH (via which/where). Never throws. */
+declare function commandExists(command: string): Promise<boolean>;
+
+/** Runs several notifiers in order, isolating failures so one can't suppress the rest. */
+declare class CompositeNotifier implements Notifier {
+    private readonly notifiers;
+    constructor(notifiers: Notifier[]);
+    notify(record: RunRecord): Promise<void>;
+}
+/**
+ * Picks the notifier from config. ConsoleNotifier ALWAYS runs: its line is the
+ * audit trail that reaches the scheduler's stdout log, so a swallowed desktop
+ * banner never costs the record. The desktop banner is layered on when opted in.
+ */
+declare function createNotifier(config: AfterburnerConfig): Notifier;
+
 interface GateConfig {
     minWeeklyHeadroomPct: number;
     safetyMarginTokens: number;
@@ -778,4 +833,4 @@ interface RepoRunOutcome {
  */
 declare function runOnce(deps: RunOnceDeps): Promise<RepoRunOutcome[]>;
 
-export { type AfterburnerConfig, type AfterburnerUserConfig, type AgentConfig, type AgentRunner, ApiKeyRunner, BASE_TASK_TOKENS, type Budget, type BudgetConfig, type BudgetProvider, type BudgetProviderOptions, type CandidateTask, type ClaudeCodeInvocation, ClaudeCodeRunner, ClaudeCodeTranscriptsBudgetProvider, type ClaudeCodeTranscriptsOptions, type ClaudeUsageBudgetOptions, ClaudeUsageBudgetProvider, ConsoleNotifier, DEFAULT_MODEL_BY_CATEGORY, type DeterministicSelectorOptions, DeterministicTaskSelector, DryRunRunner, type GateConfig, type GateDecision, JsonlRunStore, type LoadedConfig, ManualBudgetProvider, type ModelCostTable, type ModelWeightEntry, type NativeScheduleOptions, type Notifier, type RateLimitWindow, type RateLimits, type RepoConfig, type RepoRunOutcome, type RunOnceDeps, type RunOutcome, type RunRecord, type RunResult, type RunStore, type RunnerBackend, type ScheduleArtifacts, type SupportedPlatform, TASK_CATEGORIES, TASK_TAXONOMY, type TaskCategory, type TaskCategoryInfo, type TaskIdentity, type TaskSelector, type TranscriptUsageSummary, type UsageCache, type UsageCacheBudgetOptions, type UsageCacheBudgetResult, type WatchHandle, assertModelAllowed, budgetFromUsageCache, buildClaudeCodeInvocation, claudeConfigDir, configDir, configSchema, createBudgetProvider, createModelCostTable, createRunner, createSelector, dataDir, defaultClaudeProjectsDir, defaultCostTable, defaultRunStorePath, defaultUsageCachePath, defineConfig, deriveBranchName, derivePrTitle, formatConfigError, generateScheduleArtifacts, isFableModel, loadConfig, mapConfigLoadError, parseSimpleCron, readUsageCache, repoConfigSchema, runOnce, sanitizeSpawnEnv, shouldIgnite, startWatch, summarizeTranscriptUsage, taskFingerprint, writeUsageCache };
+export { type AfterburnerConfig, type AfterburnerUserConfig, type AgentConfig, type AgentRunner, ApiKeyRunner, BASE_TASK_TOKENS, type Budget, type BudgetConfig, type BudgetProvider, type BudgetProviderOptions, type CandidateTask, type ClaudeCodeInvocation, ClaudeCodeRunner, ClaudeCodeTranscriptsBudgetProvider, type ClaudeCodeTranscriptsOptions, type ClaudeUsageBudgetOptions, ClaudeUsageBudgetProvider, CompositeNotifier, ConsoleNotifier, DEFAULT_MODEL_BY_CATEGORY, DesktopNotifier, type DeterministicSelectorOptions, DeterministicTaskSelector, DryRunRunner, type GateConfig, type GateDecision, JsonlRunStore, type LoadedConfig, ManualBudgetProvider, type ModelCostTable, type ModelWeightEntry, type NativeScheduleOptions, type Notifier, type RateLimitWindow, type RateLimits, type RepoConfig, type RepoRunOutcome, type RunOnceDeps, type RunOutcome, type RunRecord, type RunResult, type RunStore, type RunnerBackend, type ScheduleArtifacts, type SupportedPlatform, TASK_CATEGORIES, TASK_TAXONOMY, type TaskCategory, type TaskCategoryInfo, type TaskIdentity, type TaskSelector, type TranscriptUsageSummary, type UsageCache, type UsageCacheBudgetOptions, type UsageCacheBudgetResult, type WatchHandle, assertModelAllowed, budgetFromUsageCache, buildClaudeCodeInvocation, claudeConfigDir, commandExists, configDir, configSchema, createBudgetProvider, createModelCostTable, createNotifier, createRunner, createSelector, dataDir, defaultClaudeProjectsDir, defaultCostTable, defaultRunStorePath, defaultUsageCachePath, defineConfig, deriveBranchName, derivePrTitle, formatConfigError, generateScheduleArtifacts, isFableModel, loadConfig, mapConfigLoadError, parseSimpleCron, readUsageCache, repoConfigSchema, runOnce, sanitizeSpawnEnv, shouldIgnite, startWatch, summarizeTranscriptUsage, taskFingerprint, writeUsageCache };

package/dist/core/index.js

@@ -4,8 +4,10 @@ import {
   ClaudeCodeRunner,
   ClaudeCodeTranscriptsBudgetProvider,
   ClaudeUsageBudgetProvider,
+  CompositeNotifier,
   ConsoleNotifier,
   DEFAULT_MODEL_BY_CATEGORY,
+  DesktopNotifier,
   DeterministicTaskSelector,
   DryRunRunner,
   JsonlRunStore,
@@ -16,10 +18,12 @@ import {
   budgetFromUsageCache,
   buildClaudeCodeInvocation,
   claudeConfigDir,
+  commandExists,
   configDir,
   configSchema,
   createBudgetProvider,
   createModelCostTable,
+  createNotifier,
   createRunner,
   createSelector,
   dataDir,
@@ -45,15 +49,17 @@ import {
   summarizeTranscriptUsage,
   taskFingerprint,
   writeUsageCache
-} from "../chunk-Z3H5GIPM.js";
+} from "../chunk-4TD2KS3A.js";
 export {
   ApiKeyRunner,
   BASE_TASK_TOKENS,
   ClaudeCodeRunner,
   ClaudeCodeTranscriptsBudgetProvider,
   ClaudeUsageBudgetProvider,
+  CompositeNotifier,
   ConsoleNotifier,
   DEFAULT_MODEL_BY_CATEGORY,
+  DesktopNotifier,
   DeterministicTaskSelector,
   DryRunRunner,
   JsonlRunStore,
@@ -64,10 +70,12 @@ export {
   budgetFromUsageCache,
   buildClaudeCodeInvocation,
   claudeConfigDir,
+  commandExists,
   configDir,
   configSchema,
   createBudgetProvider,
   createModelCostTable,
+  createNotifier,
   createRunner,
   createSelector,
   dataDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimmesz/afterburner",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Convert idle Claude subscription quota into shippable engineering work: budget-aware trigger, bounded task selection, PR-only output.",
   "license": "Apache-2.0",
   "publishConfig": {