@armstrongnate/april 0.0.2 → 0.0.4

package/README.md

@@ -8,27 +8,105 @@ april watches for GitHub issues assigned to you with a specific label, then spin
 
 - [Node.js](https://nodejs.org/) >= 22
 - [gh](https://cli.github.com/) (authenticated)
-- The `gh-webhook` extension: `gh extension install cli/gh-webhook`
+- The [`gh-webhook` extension](https://github.com/cli/gh-webhook): `gh extension install cli/gh-webhook`
 - [tmux](https://github.com/tmux/tmux)
 - [Claude Code](https://claude.ai/claude-code) CLI
 
-## Install
+## Quick install
 
 ```bash
 npm i -g @armstrongnate/april
-# or: pnpm add -g @armstrongnate/april
+april init                         # writes ~/.config/april/config.yaml + skill + env file; checks prereqs
+$EDITOR ~/.config/april/config.yaml
+april install                      # registers the user service and starts it
+april logs -f
 ```
 
-Then:
+`april init` and the daemon both verify that the `cli/gh-webhook` extension is installed and refuse to proceed without it.
+
+## Server install (full playbook)
+
+The minimal flow above leaves out auth setup and a few server-specific gotchas. This is the end-to-end recipe for a fresh Linux server.
+
+### 1. System prerequisites
 
 ```bash
-april init                         # writes ~/.config/april/config.yaml + skill + env file; checks prereqs
+# Install node 22+, tmux, gh, claude code via your usual route, then:
+gh extension install cli/gh-webhook
+```
+
+### 2. Create a Personal Access Token
+
+The systemd user service runs in a stripped-down environment — no shell config, no keyring/DBus, no credential helpers. Whatever clever auth you have set up in your interactive shell almost certainly will not be available to the daemon. **You need an explicit token in the env file.**
+
+Generate one on your GitHub host's web UI: Settings → Developer settings → Personal access tokens.
+
+**Classic PAT scopes:**
+- `repo` — issue read/write, label updates, PR creation, code access (no smaller scope works for private repo issues)
+- `admin:repo_hook` — needed for `gh webhook forward` to register and clean up its temporary `cli` webhook
+- `workflow` — only if Claude might modify `.github/workflows/*` files
+
+**Fine-grained PAT** (GHES 3.10+):
+- Repository access: select the repos
+- Permissions: Issues R/W, Pull requests R/W, Contents R/W, Webhooks R/W, Metadata R, Workflows R/W (last one optional)
+
+The daemon's own needs are smaller (Issues R/W + Webhooks R/W + Metadata R), but Claude inherits the same env when it runs inside tmux, so the token has to cover both — see [Token inheritance](#token-inheritance) below.
+
+### 3. Install the package
+
+```bash
+npm i -g @armstrongnate/april
+april init
 $EDITOR ~/.config/april/config.yaml
-april install                      # registers the user service and starts it
+```
+
+### 4. Configure auth in the env file
+
+```bash
+$EDITOR ~/.config/april/env
+```
+
+For a **GitHub Enterprise Server** host:
+
+```
+GH_HOST=your.ghes.host
+GH_ENTERPRISE_TOKEN=ghp_...
+```
+
+For **github.com**:
+
+```
+GH_TOKEN=ghp_...
+```
+
+`gh` is host-aware about which env var it reads: `GH_TOKEN` is github.com-only; `GH_ENTERPRISE_TOKEN` covers any other host (used together with `GH_HOST`). Setting `GH_TOKEN` while `GH_HOST` points elsewhere will silently fail.
+
+### 5. Install and start the service
+
+```bash
+april install
+```
+
+This writes `~/.config/systemd/user/april.service`, enables it, and starts it. The unit references the env file via `EnvironmentFile=-~/.config/april/env`, so anything you put there flows through on each restart.
+
+### 6. Enable linger (Linux servers)
+
+systemd user services stop when you log out unless linger is enabled. On any server you SSH out of:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+`april install` warns you if it sees this is off.
+
+### 7. Verify
+
+```bash
+april status
 april logs -f
 ```
 
-`april init` and the daemon both verify that the `cli/gh-webhook` extension is installed and refuse to proceed without it.
+Healthy logs include `Starting webhook forwarder for <repo>` and no immediate errors. Then label an issue with `agent:todo` and watch it kick off.
 
 ## Commands
 
@@ -48,34 +126,106 @@ The daemon reads extra env vars from `~/.config/april/env`. One `KEY=VALUE` per
 
 ```sh
 # ~/.config/april/env
+GH_HOST=your.ghes.host
+GH_ENTERPRISE_TOKEN=ghp_...
 SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
 APRIL_DEBUG=1
-GREETING="hello world"
 ```
 
-This file is seeded by `april install` (and `april init`) and is **never overwritten by reinstalls** — safe to put long-lived secrets here. After editing, `april restart`.
+This file is seeded by `april install` (and `april init`) and is **never overwritten by reinstalls** — safe to put long-lived secrets here.
+
+After editing:
+- **Linux:** `april restart`. The systemd unit re-reads the env file on each start.
+- **macOS:** `april install && april restart`. launchd has no `EnvironmentFile=` equivalent, so values are inlined into the plist at install time; you have to regenerate it after editing.
+
+### Token inheritance
 
-- On Linux, the systemd unit references it via `EnvironmentFile=-`. Changes take effect on the next restart.
-- On macOS, launchd has no equivalent directive, so values are read at install time and inlined into the plist. After editing the env file, run `april install` to regenerate the plist, then `april restart`.
+`spawner.ts` runs Claude inside tmux with `tmux new-session -d <claudeCommand>` — no login shell. So Claude inherits the daemon's env directly, including any `GH_TOKEN` / `GH_ENTERPRISE_TOKEN` you set in the env file. Practical implication: the PAT you provide has to cover what *both* april and Claude need, not just april. If you want Claude to fall back to your shell's auth (a credential helper, network-level auth, etc.), you'd need to wrap the tmux command in a login shell — not currently supported.
 
 ## Service backend
 
 - **Linux** uses systemd user services at `~/.config/systemd/user/april.service`. Logs go to the journal (`journalctl --user -u april`).
 - **macOS** uses launchd LaunchAgents at `~/Library/LaunchAgents/dev.april.daemon.plist`. Logs go to `~/Library/Logs/april/april.log`.
 
-### Linux: keep april running after logout
+### Node version managers
+
+`april install` captures the absolute path of the `node` binary it was invoked with (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`) and bakes it into the unit/plist. If you later remove or change that node version, the service will fail to start — re-run `april install` after switching.
 
-User services stop when you log out unless linger is enabled. On a server you SSH into:
+## GitHub Enterprise Server caveat
+
+`gh webhook forward` relies on GitHub's hosted webhook-relay infrastructure. **That relay is github.com-only — it is not part of GHES.** If your repos live on a GHES instance, you will see this in the logs after the daemon authenticates fine:
+
+```
+Error: you do not have access to this feature
+```
+
+The webhook extension itself works against GHES (it can authenticate, list extensions, etc.), but the actual `forward` subcommand has no relay to talk to.
+
+Workarounds (none currently shipped — file an issue if you need them wired up):
+
+1. **Direct webhook delivery.** Expose april's port publicly (reverse proxy + TLS, or a tunnel like cloudflared / tailscale funnel / ngrok), and configure a webhook on the GHES repo pointing at `https://your-server/webhook/github`. Skip `gh webhook forward` entirely.
+2. **Polling.** Replace the forwarder with a periodic poll of open issues. april already has reconciliation-on-startup; turning it into a timer is small.
+3. **Third-party relay** like smee.io.
+
+## Upgrading
 
 ```bash
-sudo loginctl enable-linger $USER
+april upgrade
 ```
 
-`april install` reminds you if it sees linger is off.
+This runs the package install, regenerates the unit/plist, and restarts the service in one go. Pass a specific version (`april upgrade 0.0.5`) to pin, or `--with pnpm|yarn` if `april upgrade` picks the wrong package manager.
 
-### Node version managers
+Manual equivalent if you want to do it yourself:
 
-`april install` captures the absolute path of the `node` binary it was invoked with (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`) and bakes it into the unit/plist. If you later remove or change that node version, the service will fail to start — re-run `april install` after switching.
+```bash
+npm i -g @armstrongnate/april@latest
+april install        # regenerates the unit/plist with any template changes (also runs daemon-reload on Linux)
+april restart
+```
+
+**If you skip `april install` after upgrading, new template features (`EnvironmentFile=`, env-var changes, etc.) will not appear in your existing unit file** — `npm` only updates the package, not anything systemd has on disk.
+
+## Troubleshooting
+
+### `Required gh extension not installed: cli/gh-webhook`
+
+Install it as the same user that runs the service:
+
+```bash
+gh extension install cli/gh-webhook
+```
+
+### `gh auth token not found for host "..."`
+
+`gh-webhook` shells out to `gh auth token` to extract a Bearer token, and your gh setup doesn't have an extractable one (you might be relying on a credential helper, network-level auth like Cloudflare Access, or a wrapper script). Add an explicit `GH_TOKEN` / `GH_ENTERPRISE_TOKEN` to `~/.config/april/env`, then `april restart`.
+
+### `you do not have access to this feature` on `gh webhook forward`
+
+Your host (likely GHES) doesn't expose the webhook-forwarding relay. See [GitHub Enterprise Server caveat](#github-enterprise-server-caveat).
+
+### Service starts but env vars in `~/.config/april/env` aren't applied
+
+You're running a unit that was generated before `EnvironmentFile=` support landed (anything from before v0.0.2). Confirm:
+
+```bash
+systemctl --user cat april | grep -i environment
+```
+
+If you don't see `EnvironmentFile=`, regenerate:
+
+```bash
+april install
+systemctl --user daemon-reload
+april restart
+```
+
+### `Token:` is empty in `gh auth status` but `gh` commands work
+
+Means your auth is provided by something other than a stored token (credential helper, network auth, wrapper). The webhook extension still needs an actual token — it doesn't matter how `gh` does its other API calls. Add `GH_TOKEN` / `GH_ENTERPRISE_TOKEN` to the env file.
+
+### Service can't find `gh` / `tmux` / `claude` even though they're on your shell PATH
+
+`april install` captures `$PATH` at install time and bakes it into the unit. If you installed any of those tools after running `april install`, re-run `april install` to recapture PATH.
 
 ## Usage
 

package/config.example.yaml

@@ -2,10 +2,7 @@ assignee: "your-github-username"
 label: "agent:todo"
 claudeSkill: "issue-worker"
 # claudeModel: "opus"              # optional, defaults to opus
-# claudeAllowedTools:              # optional, defaults to Edit, Write, Bash(*)
-#   - "Edit"
-#   - "Write"
-#   - "Bash(*)"
+# claudePermissionMode: "auto"     # optional, defaults to auto (others: default, acceptEdits, plan, bypassPermissions)
 port: 7890
 repos:
   - owner: "org"

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { backend } from "./service/index.js";
 import { run as runInit } from "./commands/init.js";
+import { run as runUpgrade } from "./commands/upgrade.js";
 const HELP = `april — issue worker
 
 Usage:
@@ -9,6 +10,8 @@ Usage:
 Commands:
   init              Copy bundled config + skill to ~/.config/april and ~/.claude
   install [--print] Install and start the user service. --print emits the unit/plist to stdout instead.
+  upgrade [VER]     Upgrade the npm package, regenerate the unit, and restart. VER defaults to "latest".
+                    Pass --with npm|pnpm|yarn to override the auto-detected package manager.
   uninstall         Stop and remove the user service
   start             Start the service
   stop              Stop the service
@@ -70,6 +73,9 @@ async function main() {
     if (cmd === "init") {
         return runInit(rest);
     }
+    if (cmd === "upgrade") {
+        return runUpgrade(rest);
+    }
     if (cmd === "daemon") {
         // Run the long-running process inline. Importing index.js triggers main();
         // we then hang forever and let its SIGINT/SIGTERM handlers terminate the process.

package/dist/commands/upgrade.js

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const PACKAGE = "@armstrongnate/april";
+function detectPackageManager() {
+    // Where this script lives reveals which global install dir it's in.
+    const here = fileURLToPath(import.meta.url);
+    if (/[\\/]\.?pnpm[\\/]|[\\/]Library[\\/]pnpm[\\/]/.test(here))
+        return "pnpm";
+    if (/[\\/]\.config[\\/]yarn[\\/]|[\\/]\.yarn[\\/]/.test(here))
+        return "yarn";
+    return "npm";
+}
+function pmInstallArgs(pm, ref) {
+    switch (pm) {
+        case "pnpm":
+            return ["add", "-g", ref];
+        case "yarn":
+            return ["global", "add", ref];
+        case "npm":
+            return ["install", "-g", ref];
+    }
+}
+function step(name, cmd, args) {
+    console.log(`\n→ ${name}`);
+    console.log(`  $ ${cmd} ${args.join(" ")}`);
+    const res = spawnSync(cmd, args, { stdio: "inherit" });
+    if ((res.status ?? 1) !== 0) {
+        throw new Error(`${name} failed (exit ${res.status})`);
+    }
+}
+export function run(args) {
+    let pm = detectPackageManager();
+    // --with <pm> override
+    const withIdx = args.indexOf("--with");
+    if (withIdx >= 0) {
+        const v = args[withIdx + 1];
+        if (v !== "npm" && v !== "pnpm" && v !== "yarn") {
+            console.error(`--with must be one of: npm, pnpm, yarn`);
+            return 2;
+        }
+        pm = v;
+    }
+    let ref = `${PACKAGE}@latest`;
+    // Allow `april upgrade <version>` to pin
+    const positional = args.filter((a, i) => !a.startsWith("--") && args[i - 1] !== "--with");
+    if (positional[0])
+        ref = `${PACKAGE}@${positional[0]}`;
+    console.log(`april upgrade — using ${pm}, target ${ref}`);
+    step(`Installing ${ref}`, pm, pmInstallArgs(pm, ref));
+    // From here on, `april` resolves to the freshly installed binary on PATH.
+    step("Regenerating service unit (april install)", "april", ["install"]);
+    step("Restarting service (april restart)", "april", ["restart"]);
+    console.log("\n✓ Upgrade complete. Tail logs with: april logs -f");
+    return 0;
+}

package/dist/config.js

@@ -63,9 +63,7 @@ export function loadConfig() {
     const label = validateString(parsed, "label", "config");
     const claudeSkill = validateString(parsed, "claudeSkill", "config");
     const claudeModel = typeof parsed.claudeModel === "string" ? parsed.claudeModel.trim() : undefined;
-    const claudeAllowedTools = Array.isArray(parsed.claudeAllowedTools)
-        ? parsed.claudeAllowedTools.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => t.trim())
-        : undefined;
+    const claudePermissionMode = typeof parsed.claudePermissionMode === "string" ? parsed.claudePermissionMode.trim() : undefined;
     const port = Number(parsed.port);
     if (!Number.isInteger(port) || port < 1024 || port > 65535) {
         throw new Error(`config: "port" must be an integer between 1024 and 65535, got: ${parsed.port}`);
@@ -96,7 +94,7 @@ export function loadConfig() {
             : undefined;
         return { owner, name, path: resolvedPath, defaultBranch, slackChannel, postWorktreeHook };
     });
-    const config = { assignee, label, claudeSkill, claudeModel, claudeAllowedTools, port, repos };
+    const config = { assignee, label, claudeSkill, claudeModel, claudePermissionMode, port, repos };
     log.info(`Config loaded: assignee=${assignee}, label=${label}, repos=${repos.map((r) => `${r.owner}/${r.name}`).join(", ")}`);
     return config;
 }

package/dist/processes.js

@@ -30,7 +30,6 @@ function cleanupStaleWebhooks(repoKey) {
 const INITIAL_BACKOFF_MS = 1000;
 const MAX_BACKOFF_MS = 30_000;
 const UPTIME_RESET_MS = 60_000;
-const MAX_CONSECUTIVE_FAILURES = 5;
 const forwarders = [];
 function spawnForwarder(config, repoKey, url) {
     const state = {
@@ -82,12 +81,8 @@ function spawnForwarder(config, repoKey, url) {
                 state.consecutiveFailures++;
                 state.backoffMs = Math.min(state.backoffMs * 2, MAX_BACKOFF_MS);
             }
-            if (state.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
-                log.error(`Forwarder for ${repoKey} failed ${MAX_CONSECUTIVE_FAILURES} consecutive times, giving up`);
-                return;
-            }
             log.warn(`Forwarder for ${repoKey} exited (code=${code}, signal=${signal}), ` +
-                `restarting in ${state.backoffMs}ms (failure ${state.consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES})`);
+                `restarting in ${state.backoffMs}ms (consecutive failures: ${state.consecutiveFailures})`);
             setTimeout(() => start(), state.backoffMs);
         });
     }

package/dist/spawner.js

@@ -149,15 +149,11 @@ export function spawnClaude(config, repo, issue, worktreePath, sessionName) {
         // Session does not exist, proceed
     }
     const model = config.claudeModel || "opus";
-    const allowedTools = [
-        ...(config.claudeAllowedTools ?? ["Read", "Search", "Edit", "Write", "Bash(*)"]),
-        ...(repo.slackChannel ? ["mcp__plugin_slack_slack__*"] : []),
-    ];
+    const permissionMode = config.claudePermissionMode || "auto";
     const slackPart = repo.slackChannel ? ` Post the PR to Slack channel #${repo.slackChannel}.` : "";
     const prompt = `/${config.claudeSkill} Read GitHub issue #${issue.number} on ${repo.owner}/${repo.name} using the gh CLI. Implement it and open a PR.${slackPart}`;
     log.debug(`Prompt: ${prompt}`);
-    const allowedToolsArgs = allowedTools.map((t) => `--allowedTools '${t}'`).join(" ");
-    const claudeCommand = `claude --model ${model} ${allowedToolsArgs}`;
+    const claudeCommand = `claude --model ${model} --permission-mode ${permissionMode}`;
     log.info(`Spawning tmux session "${sessionName}" with claude`);
     execSync(`tmux new-session -d -s ${JSON.stringify(sessionName)} -c ${JSON.stringify(worktreePath)} ${JSON.stringify(claudeCommand)}`);
     // Send the prompt via send-keys after Claude starts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armstrongnate/april",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "She does all the work so you don't have to. Watches GitHub issues and spawns Claude Code sessions to work them.",
   "type": "module",
   "bin": {

package/skills/issue-worker/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: issue-worker
-description: Autonomously work a GitHub issue end-to-end — read, implement, and open a PR with no human input required.
+description: Autonomously work a GitHub issue end-to-end — read, implement, open a PR, and monitor CI/review feedback.
 ---
 
 # issue-worker
 
-You have been assigned a GitHub issue. Work it to completion autonomously. Do not stop to ask for approval or confirmation — go straight from reading the issue to opening a PR.
+You have been assigned a GitHub issue. Work it to completion autonomously. Do not stop to ask for approval or confirmation — go straight from reading the issue to opening a PR, then monitor and respond to CI failures and review feedback.
 
 ## 1. Read the issue
 
@@ -25,16 +25,17 @@ gh issue view {issue_number} --repo {owner}/{repo} --comments
 - Write or update tests as appropriate
 - Ensure the code builds/lints/passes tests
 
-## 4. Review and simplify
+## 4. Review
 
-Run `git diff` and review your own changes. Fix any issues before committing.
+Run `/simplify` to review your changes for reuse, quality, and efficiency, and fix anything it surfaces.
 
-- **Correctness:** Does it fully address the issue? Missing edge cases?
-- **Simplify:** Can anything be combined, inlined, or removed? Prefer fewer files, less indirection, and no unnecessary abstractions.
-- **Reuse:** Are you duplicating logic that already exists in the codebase? Use existing helpers and patterns.
-- **Cleanup:** Remove leftover debug code, TODOs, unused imports, and dead code.
-- **Style:** Match the conventions of the surrounding code.
-- **Tests:** Are the tests meaningful, not just testing mocks?
+Then do a quick manual pass on things `/simplify` won't catch:
+
+- **Correctness:** Does the change fully address the issue? Any missing edge cases?
+- **Tests:** Are the tests meaningful, or are they just asserting on mocks?
+- **Cleanup:** Any leftover debug code, TODOs, or commented-out lines?
+
+Fix anything you find before moving on.
 
 ## 5. Commit, push, and open a PR
 
@@ -42,12 +43,28 @@ Run `git diff` and review your own changes. Fix any issues before committing.
 gh pr create --title "..." --body "..."
 ```
 
-Then update the issue labels:
+## 6. Post to Slack (if instructed)
+
+If the prompt specifies a Slack channel, use the Slack MCP tool to post a message with a link to the PR. Format: `<pr_url|PR> repo-name: title of the pr`
+
+## 7. Monitor CI and review feedback
+
+After creating the PR, monitor it until all checks pass and all review feedback is addressed.
+
+Loop:
+1. Sleep for 3 minutes (`sleep 180`)
+2. Check CI status: `gh pr checks {pr_number} --repo {owner}/{repo}`
+3. If any checks failed, read the failure logs, fix the issue, commit, and push
+4. Check for review comments: `gh pr view {pr_number} --repo {owner}/{repo} --comments`
+5. If there are new or unresolved comments, address them, commit, and push
+6. Repeat from step 1
+
+Stop when:
+- All CI checks pass AND
+- No unresolved review comments remain
+
+Once everything is green, update the issue labels:
 
 ```
 gh issue edit {issue_number} --repo {owner}/{repo} --add-label agent:review --remove-label agent:wip
 ```
-
-## 6. Post to Slack (if instructed)
-
-If the prompt specifies a Slack channel, use the Slack MCP tool to post a message with a link to the PR. Format: `<pr_url|PR> title of the pr`