@pimmesz/afterburner 1.0.1 → 1.0.7

package/README.md

@@ -1,14 +1,20 @@
 <p align="center">
-  <img src="assets/afterburner-logo.png" alt="Afterburner logo" width="150" />
+  <img src="assets/afterburner-logo-round.png" alt="Afterburner logo" width="144" />
 </p>
 
 <h1 align="center">Afterburner</h1>
 
 <p align="center">
-  <strong>Turn unused Claude subscription quota into small, reviewed pull requests.</strong>
+  <strong>Idle Claude quota, turned into small reviewed pull requests.</strong>
 </p>
 
 <p align="center">
+  <a href="https://github.com/pimmesz/afterburner/stargazers">
+    <img src="https://img.shields.io/github/stars/pimmesz/afterburner?style=flat&color=yellow" alt="Stars" />
+  </a>
+  <a href="https://www.npmjs.com/package/@pimmesz/afterburner">
+    <img src="https://img.shields.io/npm/v/%40pimmesz%2Fafterburner?label=npm" alt="npm version" />
+  </a>
   <a href="https://github.com/pimmesz/afterburner/actions/workflows/ci.yml">
     <img src="https://github.com/pimmesz/afterburner/actions/workflows/ci.yml/badge.svg" alt="CI status" />
   </a>
@@ -20,26 +26,47 @@
 </p>
 
 <p align="center">
-  <code>budget-aware</code> · <code>one bounded task</code> · <code>dry-run first</code> ·
-  <code>no telemetry</code>
+  <a href="#quickstart-60-seconds">Quickstart</a> ·
+  <a href="#scheduling">Scheduling</a> ·
+  <a href="#updating">Updating</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="#safety-model">Safety</a>
 </p>
 
-Afterburner watches how much of your Claude budget is left. When there's enough headroom, it
-picks one small, checkable coding task against a repo you've allowlisted and shows exactly
-what it would do.
+Afterburner is a budget-aware decision layer for coding agents. It watches your configured
+Claude headroom, chooses one bounded task from an allowlisted repo, and opens a review-first
+path toward a PR.
 
-The coding agent isn't the interesting part; that already exists. What Afterburner adds is
-the decision layer: working out when it's safe to spend, and what's worth spending on.
+It stays conservative by default: dry-run first, one task per ignition cycle, no telemetry,
+and live work only after a two-part opt-in.
 
 > Current status: the dry-run path works end to end. Live Claude Code/API execution and real
 > PR creation are still interface stubs in this version.
 
-| What it does       | Why it matters                                                          |
-| ------------------ | ----------------------------------------------------------------------- |
-| Checks both caps   | Uses weekly headroom and 5-hour session availability before doing work. |
-| Keeps work bounded | Runs one task per ignition cycle, sized to fit your configured budget.  |
-| Stays review-first | Plans a `claude/` branch and PR; live output stays away from default.   |
-| Starts safe        | Dry-run is the default, and live runs require a two-part opt-in.        |
+---
+
+## Before / After
+
+| Without Afterburner                                                                                                   | With Afterburner                                                                                                                                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Your weekly Claude quota resets on a flat-rate plan. Whatever you don't spend by the reset is gone, with no rollover. | It watches the headroom you configured, picks one bounded task from an allowlisted repo, and previews the exact `claude/` branch and PR it would open. You review everything, nothing merges itself. Dry-run today, live next. |
+
+```text
+┌─ at a glance ─────────────────────────────────────────────
+│  Safety     dry-run by default, two-part live opt-in
+│  Output     PR-only, on a claude/ branch
+│  Scope      one bounded task per run, hard token ceiling
+│  Budget     both-caps gate + safety margin
+│  Privacy    no telemetry, no phone-home
+└────────────────────────────────────────────────────────────
+```
+
+| Feature           | Default behavior                                                        |
+| ----------------- | ----------------------------------------------------------------------- |
+| Budget gate       | Checks weekly headroom and 5-hour session availability before spending. |
+| Bounded work      | Picks one small task per run and enforces a per-task token ceiling.     |
+| Review-first flow | Plans a `claude/` branch and PR; never pushes to default.               |
+| Safe install path | Starts in dry-run mode; native scheduling is opt-in.                    |
 
 > Fair use: Afterburner is for spending your own subscription quota on your own repos. It
 > doesn't get around provider limits; it keeps capacity you've already paid for from going to
@@ -103,13 +130,11 @@ These rules live in the code, not just in this README:
 
 Needs Node.js 22.12 or newer and `git` on your PATH.
 
-Heads up before you copy-paste: the first release isn't on npm yet, so install from source —
-clone the repo, then `pnpm install && pnpm build && npm install -g .`. Once published, the
-install line below works; the unscoped `afterburner` name on npm is a different, unrelated
-package, so always use the scoped `@pimmesz/afterburner`.
+Heads up before you copy-paste: the unscoped `afterburner` name on npm is a different,
+unrelated package, so always use the scoped `@pimmesz/afterburner`.
 
 ```sh
-npm install -g @pimmesz/afterburner   # once published; until then see above
+npm install -g @pimmesz/afterburner
 afterburner init             # interactive setup, writes afterburner.config.mjs
 afterburner doctor           # checks prerequisites and prints fixes
 afterburner run-once --dry-run
@@ -143,6 +168,50 @@ afterburner skill install   # copies the skill to ~/.claude/skills/afterburner/
 Then you can ask Claude Code to "run an afterburner dry run", or use `/afterburner`. Both
 drive the same CLI.
 
+---
+
+## Commands
+
+| Command                          | What it does                                                              |
+| -------------------------------- | ------------------------------------------------------------------------- |
+| `afterburner init`               | Interactive setup; writes `afterburner.config.mjs` (alias: `setup`)       |
+| `afterburner doctor`             | Check prerequisites and config; every failure prints an actionable fix    |
+| `afterburner run-once --dry-run` | Preview the next task: branch, PR title, est cost (no changes made)       |
+| `afterburner run-once --live`    | Arm a live run (needs a live engine in config; stubbed this version)      |
+| `afterburner watch`              | Foreground scheduler daemon on your configured cron                       |
+| `afterburner schedule install`   | Native launchd / systemd / schtasks entry (recommended for unattended)    |
+| `afterburner log`                | Append-only history of what ran (`--json` for machine output)             |
+| `afterburner update`             | Update to the latest release (`--print` to just show the command)         |
+| `afterburner statusline install` | Hook that caches your real `/usage` numbers for the `claude-usage` budget |
+| `afterburner skill install`      | Install the Claude Code skill into `~/.claude/skills`                     |
+| `afterburner mcp`                | MCP server front-end (stub)                                               |
+
+## Updating
+
+Afterburner checks npm at most once per day before interactive commands and prints an update
+nudge when a newer version is available. The notice goes to stderr, so JSON output from
+commands like `afterburner log --json` stays parseable. Machine-invoked commands such as
+`statusline` and `mcp` stay quiet; `update` skips the pre-check because it performs the
+update itself.
+
+```sh
+afterburner update                  # installs the latest release
+afterburner update --print          # only print the command
+afterburner update --registry=https://registry.npmjs.org/
+afterburner doctor --check-updates  # verify
+```
+
+For an npm install, `update` runs `npm install -g @pimmesz/afterburner@latest`. For a source
+checkout it rebuilds and reinstalls that checkout in place; it does not run git, so `git pull`
+first if you want new code.
+
+If a company npm proxy shadows public packages, point the install at the public registry with
+`afterburner update --registry https://registry.npmjs.org/`, or set it once globally:
+
+```sh
+npm config set @pimmesz:registry https://registry.npmjs.org/
+```
+
 ### MCP server (stub)
 
 `afterburner mcp` is a placeholder for exposing run-once, log, and doctor as MCP tools. It's
@@ -287,6 +356,16 @@ provider, prebuilt single binaries and a Homebrew tap (the build is set up so th
 to add later), the MCP server beyond its stub, and any web dashboard or vendor notification
 integration. The `Notifier` interface is the seam for that last one.
 
+---
+
+## Star history
+
+If Afterburner turned some idle quota into something useful, a star helps other people find it.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=pimmesz/afterburner&type=Date)](https://star-history.com/#pimmesz/afterburner&Date)
+
+---
+
 ## Contributing and license
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) (and [DECISIONS.md](./DECISIONS.md) for the reasoning

package/dist/cli/index.js

@@ -31,7 +31,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@pimmesz/afterburner",
-  version: "1.0.1",
+  version: "1.0.7",
   description: "Convert idle Claude subscription quota into shippable engineering work: budget-aware trigger, bounded task selection, PR-only output.",
   license: "Apache-2.0",
   publishConfig: {
@@ -43,8 +43,8 @@ var package_default = {
     node: ">=22.12"
   },
   bin: {
-    afterburner: "./dist/cli/index.js",
-    abr: "./dist/cli/index.js"
+    afterburner: "dist/cli/index.js",
+    abr: "dist/cli/index.js"
   },
   main: "./dist/core/index.js",
   types: "./dist/core/index.d.ts",
@@ -59,6 +59,7 @@ var package_default = {
     "dist",
     "skill",
     "assets/afterburner-logo.png",
+    "assets/afterburner-logo-round.png",
     "afterburner.config.example.ts",
     ".env.example"
   ],
@@ -74,7 +75,7 @@ var package_default = {
   },
   repository: {
     type: "git",
-    url: "https://github.com/pimmesz/afterburner.git"
+    url: "git+https://github.com/pimmesz/afterburner.git"
   },
   keywords: [
     "claude",
@@ -336,8 +337,10 @@ async function runDoctor(opts) {
 ${green(`${deco(emoji.rocket)}All checks passed.`)}` : `
 ${red(`${failures} check(s) failed.`)}`
   );
-  console.log(`
-${renderDoctorNextSteps({ config, configPath, failures })}`);
+  console.log(
+    `
+${renderDoctorNextSteps({ config, configPath, failed: results.filter((r) => !r.ok) })}`
+  );
   process.exitCode = failures === 0 ? 0 : 1;
 }
 function renderDoctorNextSteps(opts) {
@@ -355,9 +358,13 @@ ${nextCmd("afterburner init", "three questions; writes the config and takes it f
   then re-run:
 ${nextCmd(cmd("doctor"))}`;
   }
-  if (opts.failures > 0) {
+  if (opts.failed.length > 0) {
+    const steps = opts.failed.map(
+      (check, i) => `  ${i + 1}. ${check.fix ?? `Fix the \u2717 ${check.name} check above.`}`
+    );
     return `${next}
-  Fix the failed checks above (each prints its fix), then re-run:
+${steps.join("\n")}
+  ${opts.failed.length + 1}. Re-run the health check; all green ends with your first run command:
 ${nextCmd(cmd("doctor"))}`;
   }
   const repoNames = config.repos.map((r) => r.url);
@@ -377,7 +384,7 @@ ${next}
 ${nextCmd(cmd("run-once --dry-run"), nextNote)}`;
 }
 function checkVersion(opts) {
-  const localUpdateCommand = "pnpm build && npm install -g .";
+  const localUpdateCommand = "pnpm build && npm install -g . --force";
   const npmUpdateCommand = `npm install -g ${opts.packageName}@latest`;
   const isSourceRun = isPathInside(opts.cliEntryPath, opts.cwd);
   if (opts.latest.status === "found" && opts.latest.latestVersion) {
@@ -700,12 +707,15 @@ function registerInit(program2, packageInfo2) {
 async function runInit(opts, packageInfo2) {
   console.log(`${banner()}
 `);
-  let targetDir = process.cwd();
-  let target = join2(targetDir, "afterburner.config.mjs");
-  let backend = "dry-run";
-  let budgetProvider = "manual";
-  let repoUrl = "";
-  let verifyNow = false;
+  let answers = {
+    backend: "dry-run",
+    budgetProvider: "manual",
+    repoUrl: "",
+    verifyNow: false,
+    targetDir: process.cwd(),
+    target: join2(process.cwd(), "afterburner.config.mjs"),
+    overwriteConsented: false
+  };
   if (!opts.yes) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
       fail(
@@ -716,52 +726,7 @@ async function runInit(opts, packageInfo2) {
     const aborted = () => fail("\nAborted. No config written.");
     rl.on("SIGINT", aborted);
     try {
-      console.log(
-        "Afterburner turns unused Claude subscription quota into small, reviewed pull requests.\nDry-run first: nothing executes or spends until a live engine is set in the config\nAND you pass --live. Three questions, then an optional health check.\n"
-      );
-      console.log(bold("Step 1 of 3 \u2014 Engine (who does the work, and what it can spend)"));
-      BACKENDS.forEach((name, i) => {
-        console.log(`  ${i + 1}. ${name}: ${ENGINE_CHOICES[name]}`);
-      });
-      backend = BACKENDS[await askChoice(rl, "Engine [1]: ", BACKENDS.length)] ?? "dry-run";
-      console.log(step("Engine", backend));
-      console.log(`
-${bold("Step 2 of 3 \u2014 Repository (the allowlist of what it may touch)")}`);
-      console.log('  - a local path (e.g. ~/code/my-project, or "." for this folder)');
-      console.log("      \u2192 a dry run can scan it for candidate tasks right away");
-      console.log("  - a GitHub URL (e.g. https://github.com/you/repo)");
-      console.log("      \u2192 saved to your allowlist; used once live runs are enabled");
-      console.log(
-        "  - leave empty to skip for now (the health check flags it until a repo is added)"
-      );
-      const repoAnswer = (await rl.question("Repo path or URL: ")).trim();
-      const repoPath = localRepoPath(repoAnswer);
-      repoUrl = repoPath ?? repoAnswer;
-      const repoEcho = repoUrl === "" ? '(skipped \u2014 add one to "repos" later)' : !repoPath && !looksRemoteRepoUrl(repoAnswer) ? `${repoUrl} (not an existing directory \u2014 saved as typed; the health check will flag it)` : repoUrl;
-      console.log(step("Repo", repoEcho));
-      if (repoPath && repoPath !== targetDir && !hasConfig(repoPath)) {
-        console.log("\nWhere should the config live?");
-        console.log(`  1. ${repoPath} (next to the repo)`);
-        console.log(`  2. ${targetDir} (current directory)`);
-        if (await askChoice(rl, "Config location [1]: ", 2) === 0) {
-          targetDir = repoPath;
-          target = join2(targetDir, "afterburner.config.mjs");
-        }
-      }
-      console.log(
-        `
-${bold("Step 3 of 3 \u2014 Budget tracking (how it knows how much quota is left)")}`
-      );
-      console.log("  1. manual: trust the numbers in the config; tweak them anytime. Easy start.");
-      console.log("  2. claude-usage: read your real usage from Claude Code. Most accurate; needs");
-      console.log(
-        "     `afterburner statusline install` after setup (the health check reminds you)."
-      );
-      console.log("  3. claude-code-transcripts: estimate from local Claude Code session logs.");
-      budgetProvider = BUDGET_PROVIDERS[await askChoice(rl, "Budget tracking [1]: ", BUDGET_PROVIDERS.length)] ?? "manual";
-      console.log(step("Budget", budgetProvider));
-      const verifyAnswer = (await rl.question("\nRun the health check now (afterburner doctor)? [Y/n]: ")).trim().toLowerCase();
-      verifyNow = verifyAnswer === "" || verifyAnswer === "y" || verifyAnswer === "yes";
+      answers = await collectAnswers(rl, opts);
     } catch (error) {
       if (error?.code === "ABORT_ERR") aborted();
       throw error;
@@ -769,7 +734,8 @@ ${bold("Step 3 of 3 \u2014 Budget tracking (how it knows how much quota is left)
       rl.close();
     }
   }
-  assertCanWriteConfig(targetDir, target, opts.force === true);
+  const { backend, budgetProvider, repoUrl, verifyNow, targetDir, target } = answers;
+  assertCanWriteConfig(targetDir, target, opts.force === true || answers.overwriteConsented);
   await writeFile2(target, renderConfig(backend, budgetProvider, repoUrl), "utf8");
   console.log(`
 ${step("Config", target)}`);
@@ -789,19 +755,95 @@ ${renderOnboardingSummary({
     })}`
   );
 }
+async function collectAnswers(rl, opts, cwd = process.cwd()) {
+  let targetDir = cwd;
+  let target = join2(targetDir, "afterburner.config.mjs");
+  console.log(
+    "Afterburner turns unused Claude subscription quota into small, reviewed pull requests.\nDry-run first: nothing executes or spends until a live engine is set in the config\nAND you pass --live. Three questions, then an optional health check.\n"
+  );
+  console.log(bold("Step 1 of 3 \u2014 Engine (who does the work, and what it can spend)"));
+  BACKENDS.forEach((name, i) => {
+    console.log(`  ${i + 1}. ${name}: ${ENGINE_CHOICES[name]}`);
+  });
+  const backend = BACKENDS[await askChoice(rl, "Engine [1]: ", BACKENDS.length)] ?? "dry-run";
+  console.log(step("Engine", backend));
+  console.log(`
+${bold("Step 2 of 3 \u2014 Repository (the allowlist of what it may touch)")}`);
+  console.log('  - a local path (e.g. ~/code/my-project, or "." for this folder)');
+  console.log("      \u2192 a dry run can scan it for candidate tasks right away");
+  console.log("  - a GitHub URL (e.g. https://github.com/you/repo)");
+  console.log("      \u2192 saved to your allowlist; used once live runs are enabled");
+  console.log("  - leave empty to skip for now (the health check flags it until a repo is added)");
+  const repoAnswer = (await rl.question("Repo path or URL: ")).trim();
+  const repoPath = localRepoPath(repoAnswer, cwd);
+  const repoUrl = repoPath ?? repoAnswer;
+  const repoEcho = repoUrl === "" ? '(skipped \u2014 add one to "repos" later)' : !repoPath && !looksRemoteRepoUrl(repoAnswer) ? `${repoUrl} (not an existing directory \u2014 saved as typed; the health check will flag it)` : repoUrl;
+  console.log(step("Repo", repoEcho));
+  if (repoPath && repoPath !== targetDir && !hasConfig(repoPath)) {
+    console.log("\nWhere should the config live?");
+    console.log(`  1. ${repoPath} (next to the repo)`);
+    console.log(`  2. ${targetDir} (current directory)`);
+    if (await askChoice(rl, "Config location [1]: ", 2) === 0) {
+      targetDir = repoPath;
+      target = join2(targetDir, "afterburner.config.mjs");
+    }
+  } else if (repoPath && repoPath !== targetDir) {
+    console.log(
+      dim(
+        `Note: ${repoPath} already has an afterburner config; this one is written to the current directory.`
+      )
+    );
+  }
+  const overwriteConsented = await resolveConfigConflict(
+    rl,
+    targetDir,
+    target,
+    opts.force === true
+  );
+  console.log(
+    `
+${bold("Step 3 of 3 \u2014 Budget tracking (how it knows how much quota is left)")}`
+  );
+  console.log("  1. manual: trust the numbers in the config; tweak them anytime. Easy start.");
+  console.log("  2. claude-usage: read your real usage from Claude Code. Most accurate; needs");
+  console.log("     `afterburner statusline install` after setup (the health check reminds you).");
+  console.log("  3. claude-code-transcripts: estimate from local Claude Code session logs.");
+  const budgetProvider = BUDGET_PROVIDERS[await askChoice(rl, "Budget tracking [1]: ", BUDGET_PROVIDERS.length)] ?? "manual";
+  console.log(step("Budget", budgetProvider));
+  const verifyAnswer = (await rl.question("\nRun the health check now (afterburner doctor)? [Y/n]: ")).trim().toLowerCase();
+  const verifyNow = verifyAnswer === "" || verifyAnswer === "y" || verifyAnswer === "yes";
+  return { backend, budgetProvider, repoUrl, verifyNow, targetDir, target, overwriteConsented };
+}
+async function resolveConfigConflict(rl, targetDir, target, force) {
+  const { exact, shadowing } = configConflict(targetDir, target);
+  if (shadowing.length > 0) failShadowing(shadowing, target);
+  if (!exact || force) return false;
+  if (!await confirmOverwrite(rl, exact)) fail("Aborted. Existing config kept.");
+  return true;
+}
 function assertCanWriteConfig(targetDir, target, force) {
+  const { exact, shadowing } = configConflict(targetDir, target);
+  if (shadowing.length > 0) failShadowing(shadowing, target);
+  if (exact && !force) fail(`${exact} already exists. Pass --force to overwrite it.`);
+}
+function configConflict(targetDir, target) {
   const existing = CONFIG_FILENAMES.map((name) => join2(targetDir, name)).filter(
     (p) => existsSync3(p)
   );
-  if (existing.length > 0 && !force) {
-    fail(`${existing[0]} already exists. Pass --force to overwrite it.`);
-  }
-  const shadowing = existing.filter((p) => p !== target);
-  if (shadowing.length > 0) {
-    fail(
-      `Remove ${shadowing.join(", ")} first, or cosmiconfig will load it instead of the generated ${target}.`
-    );
-  }
+  return {
+    exact: existing.includes(target) ? target : null,
+    shadowing: existing.filter((p) => p !== target)
+  };
+}
+function failShadowing(shadowing, target) {
+  fail(
+    `Remove ${shadowing.join(", ")} first, or cosmiconfig will load it instead of the generated ${target}.`
+  );
+}
+async function confirmOverwrite(rl, target) {
+  const answer = (await rl.question(`
+${target} already exists. Overwrite it? [y/N]: `)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
 }
 function hasConfig(dir) {
   return CONFIG_FILENAMES.some((name) => existsSync3(join2(dir, name)));
@@ -1177,11 +1219,11 @@ function renderDefaultStatusLine(data) {
 }
 function readStdin() {
   if (process.stdin.isTTY) return Promise.resolve("");
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     let buf = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (c) => buf += c);
-    process.stdin.on("end", () => resolve6(buf));
+    process.stdin.on("end", () => resolve7(buf));
     process.stdin.on("error", reject);
   });
 }
@@ -1194,10 +1236,10 @@ async function readWrappedState() {
   }
 }
 function passThrough(command, input) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     const child = spawn(command, { shell: true, stdio: ["pipe", "inherit", "inherit"] });
-    child.on("error", () => resolve6());
-    child.on("close", () => resolve6());
+    child.on("error", () => resolve7());
+    child.on("close", () => resolve7());
     child.stdin.on("error", () => {
     });
     child.stdin.end(input);
@@ -1284,53 +1326,9 @@ async function uninstall() {
   );
 }
 
-// src/cli/commands/watch.ts
-function registerWatch(program2) {
-  program2.command("watch").description("Foreground scheduler daemon; prefer schedule install for unattended runs").option("--config <path>", "path to a config file").option(
-    "--live",
-    "arm live execution for every tick; only takes effect when agent.backend is a live engine (two-part opt-in)"
-  ).action(async (opts) => {
-    const { config, filepath } = await loadConfigOrExit(opts.config);
-    const live = opts.live === true;
-    const runner = createRunner(config, live);
-    const downgrade = liveDowngradeReason(config, live, filepath);
-    if (downgrade) console.error(errYellow(downgrade));
-    const { provider, source } = createBudgetProvider(config, {
-      onNote: (m) => console.error(`[afterburner] ${m}`)
-    });
-    console.log(banner());
-    console.log(
-      `${deco(emoji.jet)}${bold("watching")} ${dim(
-        `cron="${config.schedule.cron}" tz=${config.schedule.timezone} mode=${runner.backend === "dry-run" ? "dry-run" : `LIVE (${runner.backend})`} budget=${source} config=${filepath}`
-      )}`
-    );
-    const handle = startWatch({
-      cron: config.schedule.cron,
-      timezone: config.schedule.timezone,
-      onTick: async () => {
-        console.log(`[afterburner] tick ${(/* @__PURE__ */ new Date()).toISOString()}`);
-        const outcomes = await runOnce({
-          config,
-          budgetProvider: provider,
-          selector: createSelector(config),
-          runner,
-          store: new JsonlRunStore(),
-          notifier: new ConsoleNotifier()
-        });
-        for (const outcome of outcomes) {
-          console.log(`[afterburner]   ${outcome.repoUrl}: ${outcome.status}, ${outcome.reason}`);
-        }
-      }
-    });
-    const stop = () => {
-      console.log("\n[afterburner] stopping watcher");
-      handle.stop();
-      process.exit(0);
-    };
-    process.on("SIGINT", stop);
-    process.on("SIGTERM", stop);
-  });
-}
+// src/cli/commands/update.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { dirname as dirname5, resolve as resolve6 } from "path";
 
 // src/cli/update-check.ts
 import { mkdir as mkdir5, readFile as readFile2, writeFile as writeFile5 } from "fs/promises";
@@ -1349,7 +1347,7 @@ async function maybeNotifyUpdate(opts) {
     packageName: opts.packageName,
     currentVersion: opts.currentVersion,
     latestVersion: cached.latestVersion,
-    updateCommand: updateCommand(opts)
+    updateCommand: resolveUpdateCommand(opts)
   }) : null;
   if (cachedNotice) process.stderr.write(`${cachedNotice}
 `);
@@ -1368,13 +1366,13 @@ async function maybeNotifyUpdate(opts) {
       packageName: opts.packageName,
       currentVersion: opts.currentVersion,
       latestVersion,
-      updateCommand: updateCommand(opts)
+      updateCommand: resolveUpdateCommand(opts)
     });
     if (freshNotice) process.stderr.write(`${freshNotice}
 `);
   }
 }
-var UPDATE_NOTIFY_EXCLUDED = /* @__PURE__ */ new Set(["statusline", "mcp"]);
+var UPDATE_NOTIFY_EXCLUDED = /* @__PURE__ */ new Set(["statusline", "mcp", "update"]);
 function shouldNotifyForCommand(commandName) {
   return !UPDATE_NOTIFY_EXCLUDED.has(commandName);
 }
@@ -1429,8 +1427,25 @@ async function fetchLatestVersion(opts) {
     clearTimeout(timeout);
   }
 }
-function updateCommand(opts) {
-  return isPathInside2(opts.cliEntryPath, opts.cwd) ? "pnpm build && npm install -g ." : `npm install -g ${opts.packageName}@latest`;
+function detectInstallKind(opts) {
+  return isPathInside2(opts.cliEntryPath, opts.cwd) ? "source" : "global";
+}
+function detectGlobalPackageManager(cliEntryPath) {
+  const path = (cliEntryPath ?? "").replaceAll("\\", "/").toLowerCase();
+  if (path.includes("/pnpm/")) return "pnpm";
+  if (path.includes("/.bun/")) return "bun";
+  if (path.includes("/yarn/") || path.includes("/.yarn/")) return "yarn";
+  return "npm";
+}
+var GLOBAL_UPDATE_COMMANDS = {
+  npm: (packageName) => `npm install -g ${packageName}@latest`,
+  pnpm: (packageName) => `pnpm add -g ${packageName}@latest`,
+  yarn: (packageName) => `yarn global add ${packageName}@latest`,
+  bun: (packageName) => `bun add -g ${packageName}@latest`
+};
+function resolveUpdateCommand(opts) {
+  if (detectInstallKind(opts) === "source") return "pnpm build && npm install -g . --force";
+  return GLOBAL_UPDATE_COMMANDS[detectGlobalPackageManager(opts.cliEntryPath)](opts.packageName);
 }
 function isPathInside2(candidate, parent) {
   if (!candidate) return false;
@@ -1453,6 +1468,112 @@ function parseSemver2(version) {
   return [Number(major) || 0, Number(minor) || 0, Number(patch) || 0];
 }
 
+// src/cli/commands/update.ts
+var DEFAULT_REGISTRY = "https://registry.npmjs.org";
+function planUpdate(opts) {
+  const kind = detectInstallKind(opts);
+  const registry = opts.registry ?? (kind === "source" ? void 0 : DEFAULT_REGISTRY);
+  const display = withRegistry(resolveUpdateCommand(opts), registry);
+  if (opts.print) return { mode: "print", display };
+  if (kind === "source") {
+    const root = opts.cliEntryPath ? resolve6(dirname5(opts.cliEntryPath), "..", "..") : opts.cwd;
+    return {
+      mode: "execute",
+      display,
+      step: { run: display, cwd: root },
+      note: `Rebuilds the checkout at ${root}; it does not fetch new code. Run \`git pull\` there first for the latest.`
+    };
+  }
+  return { mode: "execute", display, step: { run: display } };
+}
+function registerUpdate(program2, packageInfo2) {
+  program2.command("update").description("Update Afterburner to the latest release").option("--print", "only print the update command, do not run it").option(
+    "--registry <url>",
+    "registry for the install (default: registry.npmjs.org, matching the update check)"
+  ).action(async (opts) => {
+    const plan = planUpdate({
+      ...packageInfo2,
+      cliEntryPath: process.argv[1],
+      cwd: process.cwd(),
+      print: opts.print === true,
+      registry: opts.registry
+    });
+    console.log(section(emoji.rocket, "Update Afterburner"));
+    if (plan.mode === "print" || !plan.step) {
+      console.log(nextCmd(plan.display, "run this to update"));
+      console.log(nextCmd("afterburner doctor --check-updates", "verify afterwards"));
+      return;
+    }
+    console.log(`  ${dim("will run:")} ${plan.display}`);
+    if (plan.note) console.log(`  ${yellow(plan.note)}`);
+    console.log(`
+${dim(`$ ${plan.step.run}`)}`);
+    const result = spawnSync2(plan.step.run, {
+      shell: true,
+      stdio: "inherit",
+      cwd: plan.step.cwd
+    });
+    if (result.error || result.status !== 0) {
+      const why = result.error ? result.error.message : `exit code ${result.status}`;
+      fail(`
+Update failed (${why}). Your existing install is unchanged.`);
+    }
+    console.log(`
+${green("Updated. Run `afterburner doctor --check-updates` to confirm.")}`);
+  });
+}
+function withRegistry(command, registry) {
+  return registry ? `${command} --registry=${registry}` : command;
+}
+
+// src/cli/commands/watch.ts
+function registerWatch(program2) {
+  program2.command("watch").description("Foreground scheduler daemon; prefer schedule install for unattended runs").option("--config <path>", "path to a config file").option(
+    "--live",
+    "arm live execution for every tick; only takes effect when agent.backend is a live engine (two-part opt-in)"
+  ).action(async (opts) => {
+    const { config, filepath } = await loadConfigOrExit(opts.config);
+    const live = opts.live === true;
+    const runner = createRunner(config, live);
+    const downgrade = liveDowngradeReason(config, live, filepath);
+    if (downgrade) console.error(errYellow(downgrade));
+    const { provider, source } = createBudgetProvider(config, {
+      onNote: (m) => console.error(`[afterburner] ${m}`)
+    });
+    console.log(banner());
+    console.log(
+      `${deco(emoji.jet)}${bold("watching")} ${dim(
+        `cron="${config.schedule.cron}" tz=${config.schedule.timezone} mode=${runner.backend === "dry-run" ? "dry-run" : `LIVE (${runner.backend})`} budget=${source} config=${filepath}`
+      )}`
+    );
+    const handle = startWatch({
+      cron: config.schedule.cron,
+      timezone: config.schedule.timezone,
+      onTick: async () => {
+        console.log(`[afterburner] tick ${(/* @__PURE__ */ new Date()).toISOString()}`);
+        const outcomes = await runOnce({
+          config,
+          budgetProvider: provider,
+          selector: createSelector(config),
+          runner,
+          store: new JsonlRunStore(),
+          notifier: new ConsoleNotifier()
+        });
+        for (const outcome of outcomes) {
+          console.log(`[afterburner]   ${outcome.repoUrl}: ${outcome.status}, ${outcome.reason}`);
+        }
+      }
+    });
+    const stop = () => {
+      console.log("\n[afterburner] stopping watcher");
+      handle.stop();
+      process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}
+
 // src/cli/welcome.ts
 function renderWelcome(configPath) {
   const lines = [banner(), ""];
@@ -1510,6 +1631,7 @@ registerWatch(program);
 registerSchedule(program);
 registerLog(program);
 registerSkill(program);
+registerUpdate(program, packageInfo);
 registerStatusline(program);
 registerMcp(program);
 if (process.argv.length <= 2) {

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<{
-        "dry-run": "dry-run";
         "claude-code": "claude-code";
+        "dry-run": "dry-run";
         "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<{
-            "dry-run": "dry-run";
             "claude-code": "claude-code";
+            "dry-run": "dry-run";
             "api-key": "api-key";
         }>>;
         modelByCategory: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimmesz/afterburner",
-  "version": "1.0.1",
+  "version": "1.0.7",
   "description": "Convert idle Claude subscription quota into shippable engineering work: budget-aware trigger, bounded task selection, PR-only output.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -12,8 +12,8 @@
     "node": ">=22.12"
   },
   "bin": {
-    "afterburner": "./dist/cli/index.js",
-    "abr": "./dist/cli/index.js"
+    "afterburner": "dist/cli/index.js",
+    "abr": "dist/cli/index.js"
   },
   "main": "./dist/core/index.js",
   "types": "./dist/core/index.d.ts",
@@ -28,6 +28,7 @@
     "dist",
     "skill",
     "assets/afterburner-logo.png",
+    "assets/afterburner-logo-round.png",
     "afterburner.config.example.ts",
     ".env.example"
   ],
@@ -43,7 +44,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pimmesz/afterburner.git"
+    "url": "git+https://github.com/pimmesz/afterburner.git"
   },
   "keywords": [
     "claude",