@armstrongnate/april 0.1.2 → 0.1.4

package/README.md

@@ -9,7 +9,7 @@ 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](https://github.com/cli/gh-webhook): `gh extension install cli/gh-webhook`
-- [tmux](https://github.com/tmux/tmux)
+- A session manager: [tmux](https://github.com/tmux/tmux) (default), or [herdr](https://herdr.dev) if you set `sessionManager: herdr` in config
 - One of: [Claude Code](https://claude.ai/claude-code) CLI, or [Codex](https://developers.openai.com/codex/cli) CLI
 
 ## Quick install

package/config.example.yaml

@@ -1,6 +1,7 @@
 assignee: "your-github-username"
 label: "agent:todo"
 llm: "claude"               # "claude" or "codex"
+sessionManager: "tmux"      # "tmux" (default) or "herdr"
 skill: "issue-worker"
 claude:
   # model: "opus"           # defaults to opus

package/dist/config.js

@@ -29,8 +29,8 @@ function findConfigPath() {
         `  - ${localPath}\n` +
         "Create a config.yaml (see config.example.yaml).");
 }
-function validateTools(agentCli) {
-    const tools = ["gh", "tmux", "git", agentCli];
+function validateTools(agentCli, sessionManager) {
+    const tools = ["gh", "git", agentCli, sessionManager === "herdr" ? "herdr" : "tmux"];
     for (const tool of tools) {
         try {
             execSync(`which ${tool}`, { stdio: "pipe" });
@@ -71,6 +71,15 @@ function parseLlm(parsed) {
     }
     return llmRaw;
 }
+function parseSessionManager(parsed) {
+    const val = parsed.sessionManager;
+    if (val === undefined || val === null)
+        return "tmux";
+    if (val !== "tmux" && val !== "herdr") {
+        throw new Error(`config: "sessionManager" must be "tmux" or "herdr" when provided`);
+    }
+    return val;
+}
 function parseClaudeConfig(parsed) {
     const raw = optionalObject(parsed, "claude", "config");
     if (!raw)
@@ -99,6 +108,7 @@ export function parseConfigFile(path) {
     const label = validateString(parsed, "label", "config");
     const root = parsed;
     const llm = parseLlm(root);
+    const sessionManager = parseSessionManager(root);
     const skill = validateString(root, "skill", "config");
     const claude = parseClaudeConfig(root);
     const codex = parseCodexConfig(root);
@@ -132,7 +142,7 @@ export function parseConfigFile(path) {
             : undefined;
         return { owner, name, path: resolvedPath, defaultBranch, slackChannel, postWorktreeHook };
     });
-    const config = { assignee, label, llm, skill, claude, codex, port, repos };
+    const config = { assignee, label, llm, sessionManager, skill, claude, codex, port, repos };
     return config;
 }
 /**
@@ -160,7 +170,7 @@ export function loadConfig() {
     const configPath = findConfigPath();
     log.info(`Loading config from ${configPath}`);
     const config = parseConfigFile(configPath);
-    validateTools(getAgent(config.llm).cli);
+    validateTools(getAgent(config.llm).cli, config.sessionManager ?? "tmux");
     log.info(`Config loaded: assignee=${config.assignee}, label=${config.label}, llm=${config.llm}, ` +
         `repos=${config.repos.map((r) => `${r.owner}/${r.name}`).join(", ")}`);
     return config;

package/dist/index.js

@@ -54,7 +54,7 @@ async function main() {
         log.info(`Checking for missed issues in ${repo.owner}/${repo.name}...`);
         const openIssues = fetchOpenIssues(repo, config);
         for (const issue of openIssues) {
-            if (!isIssueActive(repo, issue.number)) {
+            if (!(await isIssueActive(repo, issue.number, config))) {
                 log.info(`Found missed issue: #${issue.number} — "${issue.title}"`);
                 await handleNewIssue(repo, issue, config);
             }
@@ -76,12 +76,13 @@ async function main() {
     // 5. Start webhook forwarders
     const children = startWebhookForwarders(config);
     // Print startup banner
-    const { worktrees, sessions } = getActiveCounts(config);
+    const { worktrees, sessions } = await getActiveCounts(config);
     const repoList = config.repos.map((r) => `${r.owner}/${r.name}`).join(", ");
     console.log(`  Assignee: ${config.assignee}`);
     console.log(`  Label: ${config.label}`);
     console.log(`  Repos: ${repoList}`);
-    console.log(`  Active: ${worktrees} worktree${worktrees === 1 ? "" : "s"}, ${sessions} tmux session${sessions === 1 ? "" : "s"}`);
+    console.log(`  Session manager: ${config.sessionManager ?? "tmux"}`);
+    console.log(`  Active: ${worktrees} worktree${worktrees === 1 ? "" : "s"}, ${sessions} session${sessions === 1 ? "" : "s"}`);
     console.log(`  Server: http://localhost:${config.port}`);
     console.log(`  Forwarders: ${children.length} active`);
     console.log("");

package/dist/server.js

@@ -30,7 +30,7 @@ export async function startServer(config, onNewIssue) {
             const result = parseWebhookEvent(headers, body, config);
             if (result?.kind === "issue_assigned") {
                 const key = `issue:${result.repo.owner}/${result.repo.name}#${result.issue.number}`;
-                if (isIssueActive(result.repo, result.issue.number)) {
+                if (await isIssueActive(result.repo, result.issue.number, config)) {
                     log.debug(`Issue ${key} already active, ignoring webhook`);
                 }
                 else if (isRecentlyProcessed(key)) {
@@ -53,7 +53,7 @@ export async function startServer(config, onNewIssue) {
                     markProcessed(key);
                     log.info(`Processing webhook for ${key}`);
                     try {
-                        handlePrClosed(result.repo, result.branch);
+                        await handlePrClosed(result.repo, result.branch, config);
                     }
                     catch (err) {
                         log.error(`Error handling PR close: ${err instanceof Error ? err.message : String(err)}`);

package/dist/service/launchd.js

@@ -59,7 +59,7 @@ ${envEntries}
     <key>ProcessType</key>
     <string>Background</string>
     <!-- launchd's equivalent of systemd's KillMode=process: when the daemon
-         exits, don't kill children that share its process group. Keeps tmux
+         exits, don't kill children that share its process group. Keeps agent
          sessions and any in-flight agent work alive across restarts. -->
     <key>AbandonProcessGroup</key>
     <true/>

package/dist/service/systemd.js

@@ -15,7 +15,8 @@ function runSystemctl(args) {
 export function unitContents() {
     const node = nodeBinaryPath();
     const entry = daemonEntryPath();
-    // Capture caller's PATH so child has access to gh, tmux, git, and the configured agent CLI.
+    // Capture caller's PATH so child has access to gh, the session manager
+    // (tmux/herdr), git, and the configured agent CLI.
     const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
     return `[Unit]
 Description=april — issue worker
@@ -32,7 +33,7 @@ Environment=NODE_ENV=production
 EnvironmentFile=-${envFilePath()}
 StandardOutput=journal
 StandardError=journal
-# Only signal the main process on stop; leave tmux sessions and any other
+# Only signal the main process on stop; leave agent sessions and any other
 # children running so an april restart doesn't trash in-flight agent work.
 # The daemon's own shutdown handler still SIGTERMs the gh webhook forwarders.
 KillMode=process

package/dist/session/herdr-client.js

@@ -0,0 +1,83 @@
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Minimal client for the herdr socket API.
+ *
+ * Transport: newline-delimited JSON over a Unix domain socket. Each request is
+ * `{ id, method, params }` on one line; the matching response is `{ id, result }`
+ * or `{ id, error: { code, message } }`. The server may also emit unrelated
+ * event lines (different/absent id), which we skip.
+ *
+ * Socket resolution mirrors herdr's own order:
+ *   HERDR_SOCKET_PATH -> HERDR_SESSION (named) -> default.
+ *
+ * We open a fresh connection per request. april's call volume is low (a handful
+ * of calls per issue), so this trades a negligible amount of overhead for not
+ * having to manage a long-lived multiplexed connection or reconnect logic.
+ */
+function socketPath() {
+    const explicit = process.env.HERDR_SOCKET_PATH;
+    if (explicit)
+        return explicit;
+    const sessionName = process.env.HERDR_SESSION;
+    if (sessionName) {
+        return join(homedir(), ".config", "herdr", "sessions", sessionName, "herdr.sock");
+    }
+    return join(homedir(), ".config", "herdr", "herdr.sock");
+}
+let reqCounter = 0;
+export function herdrRequest(method, params = {}, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+        const id = `april_${++reqCounter}`;
+        const sock = connect(socketPath());
+        let buf = "";
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            sock.end();
+            fn();
+        };
+        const timer = setTimeout(() => {
+            finish(() => reject(new Error(`herdr request "${method}" timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        sock.on("connect", () => {
+            sock.write(JSON.stringify({ id, method, params }) + "\n");
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf-8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) !== -1) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (!line)
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue; // not a complete/valid JSON line; ignore
+                }
+                if (msg.id !== id)
+                    continue; // unrelated event or response
+                if (msg.error) {
+                    finish(() => reject(new Error(`herdr ${method}: ${msg.error.code} — ${msg.error.message}`)));
+                }
+                else {
+                    finish(() => resolve(msg.result));
+                }
+                return;
+            }
+        });
+        sock.on("error", (err) => {
+            finish(() => reject(new Error(`herdr socket error on "${method}": ${err.message}`)));
+        });
+        sock.on("close", () => {
+            finish(() => reject(new Error(`herdr connection closed before "${method}" responded`)));
+        });
+    });
+}

package/dist/session/herdr.js

@@ -0,0 +1,215 @@
+import { createLogger } from "../logger.js";
+import { herdrRequest } from "./herdr-client.js";
+const log = createLogger("session:herdr");
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+async function listWorkspaces() {
+    const res = await herdrRequest("workspace.list");
+    return res.workspaces ?? [];
+}
+async function findByLabel(name) {
+    return (await listWorkspaces()).find((w) => w.label === name);
+}
+async function listPaneIds(workspaceId) {
+    const res = await herdrRequest("pane.list", { workspace_id: workspaceId });
+    return (res.panes ?? []).map((p) => p.pane_id);
+}
+/**
+ * Best-effort wait until the freshly launched agent is accepting input.
+ *
+ * This is the herdr-native replacement for april's blind `setTimeout` dance:
+ * we poll the pane's agent_status and proceed as soon as it's recognized,
+ * falling back to a fixed wait if detection never settles.
+ */
+async function waitForAgentReady(paneId, attempts = 10, intervalMs = 1000) {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const status = await paneStatus(paneId);
+            if (status && status !== "unknown")
+                return;
+        }
+        catch {
+            // transient; keep polling
+        }
+        await delay(intervalMs);
+    }
+    log.warn(`Agent in pane ${paneId} never reported a known status; proceeding anyway`);
+}
+const SUBMIT_SETTLE_MS = 1000;
+const INJECT_ATTEMPTS = 4;
+/** Read a pane's current agent status (undefined if unavailable). */
+async function paneStatus(paneId) {
+    const res = await herdrRequest("pane.get", { pane_id: paneId });
+    return res.pane?.agent_status;
+}
+/** A status that means the agent left the input box and picked up the prompt. */
+function isAccepted(status) {
+    return status !== undefined && status !== "idle" && status !== "unknown";
+}
+const normalizeWhitespace = (text) => text.replace(/\s+/g, " ");
+/**
+ * A short, wrap-safe slice of the prompt to look for in the pane's input box.
+ * Kept brief (and whitespace-normalized) so terminal wrapping or the `❯ `
+ * prefix don't break the substring match against what pane.read returns.
+ */
+function promptSignature(prompt) {
+    return normalizeWhitespace(prompt).trim().slice(0, 24);
+}
+/** Visible (on-screen) text of a pane; "" if it can't be read. */
+async function readVisible(paneId) {
+    try {
+        const res = await herdrRequest("pane.read", {
+            pane_id: paneId,
+            source: "visible",
+        });
+        return res.read?.text ?? "";
+    }
+    catch {
+        // transient; treat as "can't confirm"
+        return "";
+    }
+}
+/** Whether our prompt text currently appears in the pane (i.e. the input box). */
+async function promptIsVisible(paneId, signature) {
+    if (!signature)
+        return true;
+    return normalizeWhitespace(await readVisible(paneId)).includes(signature);
+}
+/**
+ * Wait for the agent to leave `idle` — confirmation that the Enter submitted
+ * and the agent picked up the prompt. `working`/`blocked`/`done` all mean the
+ * prompt was accepted; staying `idle` means it's still sitting in the input box.
+ */
+async function confirmSubmitted(paneId, attempts = 6, intervalMs = 500) {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            if (isAccepted(await paneStatus(paneId)))
+                return true;
+        }
+        catch {
+            // transient; keep polling
+        }
+        await delay(intervalMs);
+    }
+    return false;
+}
+/**
+ * Inject the prompt and verify the agent actually picked it up, retrying around
+ * the two misfires documented in the header. Returns the agent status when we
+ * stop so the caller can log the outcome.
+ *
+ * The loop is self-correcting: each pass first checks whether the agent is
+ * already working (a prior Enter landed even if its confirm timed out — never
+ * retype into a running agent), then ensures the text is in the box (typing it
+ * only if absent, so retries can't duplicate it), then submits and confirms.
+ */
+async function injectPrompt(paneId, prompt) {
+    const signature = promptSignature(prompt);
+    for (let attempt = 1; attempt <= INJECT_ATTEMPTS; attempt++) {
+        const status = await paneStatus(paneId).catch(() => undefined);
+        if (isAccepted(status)) {
+            if (attempt > 1)
+                log.info(`Agent in pane ${paneId} accepted the prompt (status: ${status})`);
+            return status;
+        }
+        // 1. Ensure our text is in the input box — type it only if it isn't there,
+        //    so a retry after a failed submit doesn't append a second copy.
+        if (!(await promptIsVisible(paneId, signature))) {
+            await herdrRequest("pane.send_text", { pane_id: paneId, text: prompt });
+            await delay(SUBMIT_SETTLE_MS);
+        }
+        // 2. Still not there → a Claude startup screen ate the burst. Dismiss it
+        //    with Enter and loop to retype. (That Enter may instead have submitted
+        //    real text on a flaky read, so re-check status before retrying.)
+        if (!(await promptIsVisible(paneId, signature))) {
+            log.warn(`Prompt text not visible in pane ${paneId} input (attempt ${attempt}/${INJECT_ATTEMPTS}); dismissing startup screen and retrying`);
+            await herdrRequest("pane.send_keys", { pane_id: paneId, keys: ["Enter"] });
+            await delay(SUBMIT_SETTLE_MS);
+            const dismissed = await paneStatus(paneId).catch(() => undefined);
+            if (isAccepted(dismissed))
+                return dismissed;
+            continue;
+        }
+        // 3. Text is in the box — submit it and confirm via agent_status.
+        await herdrRequest("pane.send_keys", { pane_id: paneId, keys: ["Enter"] });
+        if (await confirmSubmitted(paneId)) {
+            const accepted = await paneStatus(paneId).catch(() => undefined);
+            log.info(`Prompt submitted to pane ${paneId} on attempt ${attempt} (status: ${accepted ?? "unknown"})`);
+            return accepted;
+        }
+        log.warn(`Agent in pane ${paneId} still idle after Enter (attempt ${attempt}/${INJECT_ATTEMPTS}); will retry`);
+    }
+    return paneStatus(paneId).catch(() => undefined);
+}
+export const herdrBackend = {
+    async listSessions() {
+        return (await listWorkspaces())
+            .map((w) => w.label)
+            .filter((l) => typeof l === "string" && l.length > 0);
+    },
+    async hasSession(name) {
+        return (await findByLabel(name)) !== undefined;
+    },
+    async spawn({ name, cwd, command, prompt }) {
+        if (await this.hasSession(name)) {
+            log.info(`herdr workspace "${name}" already exists, skipping`);
+            return;
+        }
+        // Create a dedicated labeled workspace for this issue (the slug is our
+        // identity key for list/dedupe/kill). It also spawns a root shell pane.
+        const created = await herdrRequest("workspace.create", { cwd, label: name });
+        const workspaceId = created.workspace?.workspace_id;
+        if (!workspaceId) {
+            throw new Error(`herdr workspace.create for "${name}" returned no workspace id`);
+        }
+        // Launch the agent as the pane's own process via a non-interactive shell,
+        // placed explicitly in our workspace.
+        const started = await herdrRequest("agent.start", {
+            name,
+            cwd,
+            argv: ["sh", "-c", `exec ${command}`],
+            workspace_id: workspaceId,
+        });
+        let paneId = started.agent?.pane_id;
+        if (!paneId) {
+            throw new Error(`herdr agent.start for "${name}" returned no pane id`);
+        }
+        // Drop the idle root shell pane so the workspace holds only the agent.
+        // Closing it renumbers the remaining pane, so re-resolve the agent's pane.
+        const rootPaneId = created.root_pane?.pane_id;
+        if (rootPaneId) {
+            try {
+                await herdrRequest("pane.close", { pane_id: rootPaneId });
+                await delay(300);
+                const panes = await listPaneIds(workspaceId);
+                if (panes.length === 1) {
+                    paneId = panes[0];
+                }
+                else {
+                    log.warn(`Expected 1 pane after closing root shell in "${name}", found ${panes.length}; keeping ${paneId}`);
+                }
+            }
+            catch (err) {
+                log.warn(`Could not close root shell pane in "${name}": ${err instanceof Error ? err.message : String(err)}; leaving it`);
+            }
+        }
+        log.info(`Started agent in herdr workspace "${name}" (pane ${paneId})`);
+        // Wait until the agent is up, then inject the prompt and verify it landed.
+        await waitForAgentReady(paneId);
+        const status = await injectPrompt(paneId, prompt);
+        if (isAccepted(status)) {
+            log.info(`Prompt delivered to herdr workspace "${name}" — agent is ${status} (pane ${paneId})`);
+        }
+        else {
+            log.error(`Prompt may NOT have been accepted in herdr workspace "${name}" — agent status "${status ?? "unavailable"}" after ${INJECT_ATTEMPTS} attempts (pane ${paneId}). The session likely needs manual attention.`);
+        }
+    },
+    async kill(name) {
+        const ws = await findByLabel(name);
+        if (!ws) {
+            log.debug(`No herdr workspace labeled "${name}"; nothing to kill`);
+            return;
+        }
+        await herdrRequest("workspace.close", { workspace_id: ws.workspace_id });
+        log.info(`Closed herdr workspace "${name}"`);
+    },
+};

package/dist/session/index.js

@@ -0,0 +1,15 @@
+import { tmuxBackend } from "./tmux.js";
+import { herdrBackend } from "./herdr.js";
+/**
+ * Pick the session backend for this install. Defaults to tmux so existing
+ * configs keep working unchanged.
+ */
+export function getSessionBackend(config) {
+    switch (config.sessionManager) {
+        case "herdr":
+            return herdrBackend;
+        case "tmux":
+        default:
+            return tmuxBackend;
+    }
+}

package/dist/session/tmux.js

@@ -0,0 +1,57 @@
+import { execSync } from "node:child_process";
+import { createLogger } from "../logger.js";
+const log = createLogger("session:tmux");
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * tmux backend. This is april's current behavior, lifted verbatim out of
+ * spawner.ts and behind the SessionBackend contract. Default backend, so
+ * existing installs are unaffected.
+ */
+export const tmuxBackend = {
+    async listSessions() {
+        try {
+            const output = execSync("tmux list-sessions -F '#{session_name}'", {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            return output.trim().split("\n").filter(Boolean);
+        }
+        catch {
+            // tmux not running or no sessions
+            return [];
+        }
+    },
+    async hasSession(name) {
+        try {
+            execSync(`tmux has-session -t ${JSON.stringify(name)}`, { stdio: "pipe" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async spawn({ name, cwd, command, prompt }) {
+        if (await this.hasSession(name)) {
+            log.info(`tmux session "${name}" already exists, skipping`);
+            return;
+        }
+        execSync(`tmux new-session -d -s ${JSON.stringify(name)} -c ${JSON.stringify(cwd)} ${JSON.stringify(command)}`);
+        // Send text first, then Enter after a short delay so the agent's input is ready.
+        const escapedPrompt = prompt.replace(/'/g, "'\\''");
+        const session = JSON.stringify(name);
+        await delay(3000);
+        execSync(`tmux send-keys -t ${session} '${escapedPrompt}'`, { stdio: "pipe" });
+        await delay(1000);
+        execSync(`tmux send-keys -t ${session} C-m`, { stdio: "pipe" });
+        log.info(`Prompt sent to tmux session "${name}"`);
+    },
+    async kill(name) {
+        try {
+            execSync(`tmux kill-session -t ${JSON.stringify(name)}`, { stdio: "pipe" });
+            log.info(`Killed tmux session ${name}`);
+        }
+        catch {
+            // Session already gone — fine
+        }
+    },
+};

package/dist/session/types.js

@@ -0,0 +1,18 @@
+/**
+ * Session backend abstraction.
+ *
+ * april needs only four primitives from whatever runs its agent sessions.
+ * Today those map to tmux; this interface lets a herdr (or any other) backend
+ * drop in behind the same contract.
+ *
+ *   listSessions  -> tmux `list-sessions`        / herdr `workspace.list`
+ *   hasSession    -> tmux `has-session`          / herdr `workspace.list` + filter
+ *   spawn         -> tmux `new-session` + send   / herdr `workspace.create` + `pane.send_*`
+ *   kill          -> tmux `kill-session`         / herdr `workspace.close`
+ *
+ * "name" is the stable identity april assigns — the branch slug, e.g.
+ * `gh-123-fix-foo`. tmux uses it directly as the session name. herdr assigns
+ * its own ids, so the backend stores the slug as the workspace `label` and
+ * resolves label -> id on demand.
+ */
+export {};

package/dist/spawner.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { createLogger } from "./logger.js";
 import { makeSlug } from "./slug.js";
 import { getAgent } from "./agents.js";
+import { getSessionBackend } from "./session/index.js";
 const log = createLogger("spawner");
 function checkWorktreesIgnored(repoPath) {
     const gitignorePath = join(repoPath, ".gitignore");
@@ -23,10 +24,11 @@ function checkWorktreesIgnored(repoPath) {
     }
 }
 /**
- * Check if an issue is already active by looking at the filesystem and tmux.
- * Matches any worktree dir or tmux session starting with `gh-{issueNumber}-`.
+ * Check if an issue is already active by looking at the filesystem and the
+ * session backend. Matches any worktree dir or session starting with
+ * `gh-{issueNumber}-`.
  */
-export function isIssueActive(repo, issueNumber) {
+export async function isIssueActive(repo, issueNumber, config) {
     const prefix = `gh-${issueNumber}-`;
     // Check worktrees on disk
     const worktreesDir = join(repo.path, ".worktrees");
@@ -38,27 +40,19 @@ export function isIssueActive(repo, issueNumber) {
             return true;
         }
     }
-    // Check tmux sessions
-    try {
-        const output = execSync("tmux list-sessions -F '#{session_name}'", {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        const match = output.trim().split("\n").find((s) => s.startsWith(prefix));
-        if (match) {
-            log.info(`Skipping issue #${issueNumber}: existing tmux session found (${match})`);
-            return true;
-        }
-    }
-    catch {
-        // tmux not running or no sessions
+    // Check active sessions
+    const sessions = await getSessionBackend(config).listSessions();
+    const match = sessions.find((s) => s.startsWith(prefix));
+    if (match) {
+        log.info(`Skipping issue #${issueNumber}: existing session found (${match})`);
+        return true;
     }
     return false;
 }
 /**
- * Count active worktrees and tmux sessions across all configured repos.
+ * Count active worktrees and sessions across all configured repos.
  */
-export function getActiveCounts(config) {
+export async function getActiveCounts(config) {
     let worktrees = 0;
     for (const repo of config.repos) {
         const dir = join(repo.path, ".worktrees");
@@ -66,17 +60,8 @@ export function getActiveCounts(config) {
             worktrees += readdirSync(dir).filter((d) => d.startsWith("gh-")).length;
         }
     }
-    let sessions = 0;
-    try {
-        const output = execSync("tmux list-sessions -F '#{session_name}'", {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        sessions = output.trim().split("\n").filter((s) => s.startsWith("gh-")).length;
-    }
-    catch {
-        // tmux not running
-    }
+    const sessionNames = await getSessionBackend(config).listSessions();
+    const sessions = sessionNames.filter((s) => s.startsWith("gh-")).length;
     return { worktrees, sessions };
 }
 export async function createWorktree(repo, branch) {
@@ -139,50 +124,23 @@ export async function createWorktree(repo, branch) {
     }
     return worktreePath;
 }
-export function spawnAgent(config, repo, issue, worktreePath, sessionName) {
-    // Check if session already exists
-    try {
-        execSync(`tmux has-session -t ${JSON.stringify(sessionName)}`, { stdio: "pipe" });
-        log.info(`tmux session "${sessionName}" already exists, skipping`);
-        return;
-    }
-    catch {
-        // Session does not exist, proceed
-    }
+export async function spawnAgent(config, repo, issue, worktreePath, sessionName) {
+    const backend = getSessionBackend(config);
     const agent = getAgent(config.llm);
     const slackPart = repo.slackChannel ? ` Post the PR to Slack channel #${repo.slackChannel}.` : "";
     const promptBody = `Read GitHub issue #${issue.number} on ${repo.owner}/${repo.name} using the gh CLI. Implement it and open a PR.${slackPart}`;
     const prompt = agent.buildPrompt(config.skill, promptBody);
     log.debug(`Prompt: ${prompt}`);
     const agentCommand = agent.buildCommand(config);
-    log.info(`Spawning tmux session "${sessionName}" with ${agent.kind}`);
-    execSync(`tmux new-session -d -s ${JSON.stringify(sessionName)} -c ${JSON.stringify(worktreePath)} ${JSON.stringify(agentCommand)}`);
-    // Send the prompt via send-keys after the agent starts
-    const escapedPrompt = prompt.replace(/'/g, "'\\''");
-    const session = JSON.stringify(sessionName);
-    setTimeout(() => {
-        try {
-            // Send text first, then Enter after a short delay to ensure the agent's input is ready
-            execSync(`tmux send-keys -t ${session} '${escapedPrompt}'`, { stdio: "pipe" });
-            setTimeout(() => {
-                try {
-                    execSync(`tmux send-keys -t ${session} C-m`, { stdio: "pipe" });
-                    log.info(`Prompt sent to tmux session "${sessionName}"`);
-                }
-                catch (err) {
-                    log.warn(`Failed to send Enter to session "${sessionName}": ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }, 1000);
-        }
-        catch (err) {
-            log.warn(`Failed to send prompt to session "${sessionName}": ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }, 3000);
-    log.info(`tmux session "${sessionName}" started`);
+    log.info(`Spawning session "${sessionName}" with ${agent.kind}`);
+    // The backend is responsible for the dedupe check, launching the agent in the
+    // worktree, and injecting the prompt once it's ready.
+    await backend.spawn({ name: sessionName, cwd: worktreePath, command: agentCommand, prompt });
+    log.info(`Session "${sessionName}" started`);
 }
 export async function handleNewIssue(repo, issue, config) {
-    // Check if already active via filesystem/tmux
-    if (isIssueActive(repo, issue.number)) {
+    // Check if already active via filesystem/session backend
+    if (await isIssueActive(repo, issue.number, config)) {
         log.info(`Issue #${issue.number} already active in ${repo.owner}/${repo.name}, skipping`);
         return;
     }
@@ -196,9 +154,9 @@ export async function handleNewIssue(repo, issue, config) {
         log.error(`Failed to create worktree for #${issue.number}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    // Spawn tmux + agent
+    // Spawn session + agent
     try {
-        spawnAgent(config, repo, issue, worktreePath, slug);
+        await spawnAgent(config, repo, issue, worktreePath, slug);
     }
     catch (err) {
         log.error(`Failed to spawn ${config.llm} for #${issue.number}: ${err instanceof Error ? err.message : String(err)}`);
@@ -219,7 +177,7 @@ export async function handleNewIssue(repo, issue, config) {
     }
     log.info(`Issue #${issue.number} (${repo.owner}/${repo.name}) is now active`);
 }
-export function handlePrClosed(repo, branch) {
+export async function handlePrClosed(repo, branch, config) {
     log.info(`Cleaning up worktree for branch ${branch} (${repo.owner}/${repo.name})`);
     try {
         execFileSync("wt", ["remove", branch, "-f", "-D"], {
@@ -232,13 +190,7 @@ export function handlePrClosed(repo, branch) {
     catch (err) {
         log.warn(`wt remove ${branch} failed: ${err instanceof Error ? err.message : String(err)}`);
     }
-    try {
-        execFileSync("tmux", ["kill-session", "-t", branch], { stdio: "pipe" });
-        log.info(`Killed tmux session ${branch}`);
-    }
-    catch {
-        // Session already gone — fine
-    }
+    await getSessionBackend(config).kill(branch);
     log.info(`Cleanup complete for ${branch}`);
 }
 export function fetchOpenIssues(repo, config) {

package/package.json

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