@agilemonster/mcp-server 1.0.25 → 1.0.26

package/README.md

@@ -14,7 +14,9 @@ Seamlessly connects your Agile Monster boards with your favorite developer AI ag
 
 ## ⚡ Quick Start: Adding to your AI Agent
 
-Generate a **Personal API Key** in Agile Monster ([https://app.agilemonster.com](https://app.agilemonster.com) -> Profile -> API Keys). Your key will look like `am_live_...`.
+The quickest way is the one command in [Connect a project folder](#-connect-a-project-folder-bootstrap) below: it does everything in this section for you.
+
+To set a tool up by hand, generate a **Personal API Key** in Agile Monster ([https://app.agilemonster.com](https://app.agilemonster.com) -> Profile -> AI Agents & API Keys -> Generate API key). Your key will look like `am_live_...`.
 
 ### 1. Cursor (`.cursor/mcp.json` or Global Settings)
 ```json
@@ -58,14 +60,19 @@ Add to your Antigravity MCP directory (`~/.gemini/antigravity/mcp/agilemonster`
 
 ---
 
-## 📁 1-Click Project Initialization (`init`)
+## 📁 Connect a project folder (`bootstrap`)
 
-To automatically bind your repository to an Agile Monster board and generate operational instructions for your AI agents in one command, run:
+Open a terminal in your project folder and run this once (it needs [Node.js](https://nodejs.org) 18.14 or newer):
 
 ```bash
-npx @agilemonster/mcp-server init
+npx -y @agilemonster/mcp-server bootstrap
 ```
 
+It asks for your API key the first time, lets you pick the board, writes the files below, **installs the
+background runner** (see the next section) and ends by telling you which coding agent on this computer is
+ready. `init` and `setup` are the same command. Add `--board="Board name"` to skip the question, or
+`--no-service` to leave the background runner out.
+
 This generates:
 1. `.agilemonster.json` — Binds the local repository to the board UUID, list columns, and default agent provider.
 2. `AGENTS.md` — Codified operational rules for autonomous agents (Cursor, Claude Code, Antigravity, etc.) so they know when to claim tasks, ask clarifying questions, log progress, and submit work for human testing.
@@ -93,14 +100,37 @@ Agents have access to these purpose-built lifecycle tools:
 
 ## 🧠 Who works a card that is queued from the board
 
-A card you assign to an agent in the web app is picked up by the background runner on your machine. The
-runner hands it to a **real coding agent running headless in the project folder** — the same agent you use
+A card you assign to an agent in the web app is picked up by the background runner on your machine.
+
+### The background runner
+
+`bootstrap` installs the runner as a service that starts with the computer, so cards are worked whether or
+not a coding tool is open. Without it, cards are only picked up while an AI coding tool with this MCP server
+is open in the project folder.
+
+```bash
+npx -y @agilemonster/mcp-server service status      # is it installed and running?
+npx -y @agilemonster/mcp-server service install     # install or repair it
+npx -y @agilemonster/mcp-server service uninstall   # stop and remove it
+```
+
+- **macOS**: a launchd agent (`~/Library/LaunchAgents/com.agilemonster.pulse.plist`). **Linux**: a systemd
+  user unit (`agilemonster-runner.service`). **Windows**: not available as a service yet; keep your coding
+  tool open, or run `npx -y @agilemonster/mcp-server pulse-daemon` in a terminal.
+- The service runs its own copy of this package from `~/.agilemonster/runner` and keeps it up to date.
+- A runner that was set up by hand is left alone unless you pass `--force`.
+- The board shows the result: next to a waiting card it says whether a computer is connected, whether it is
+  there right now, and which agent will do the work.
+
+### The agent that does the work
+
+The runner hands a card to a **real coding agent running headless in the project folder** — the same agent you use
 in the IDE, with the same ability to search the code, open what it finds, run the build and fix what it broke:
 
 | Card's agent | Command line agent used | One-time setup |
 | :--- | :--- | :--- |
 | Cursor | `cursor-agent -p --force` | `curl https://cursor.com/install -fsS \| bash`, then `cursor-agent login` |
-| Claude Code | `claude -p --permission-mode acceptEdits` | `npm install -g @anthropic-ai/claude-code`, then `claude auth login` |
+| Claude Code | `claude -p --permission-mode acceptEdits --allowedTools Bash` | `npm install -g @anthropic-ai/claude-code`, then `claude auth login` |
 | Codex | `codex exec --sandbox workspace-write` | `npm install -g @openai/codex`, then `codex login` |
 
 The runner also finds an agent that is not on your `PATH` — for example the Codex CLI that the Codex app and
@@ -153,7 +183,8 @@ What the runner guarantees:
 State lives outside your repositories: `~/.agilemonster/projects/` (per-project deployment history) and
 `~/.agilemonster/logs/daemon.jsonl` (structured daemon log).
 
-Card reply syntax: `retry` · `deploy: github_actions` · `deploy: docker_compose` · `deploy: manual` · `deploy: ./deploy/deploy.sh` · `live url: https://example.com`
+When the runner asks a question, the card shows the answers it accepts as buttons, so nobody has to type
+these. They still work as typed replies: `retry` · `deploy: github_actions` · `deploy: docker_compose` · `deploy: manual` · `deploy: ./deploy/deploy.sh` · `live url: https://example.com`
 
 ---
 

package/bin/mcp.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { runStdioServer, runBackgroundPulseDaemon } from '../dist/server.js';
-import { MCP_SERVER_VERSION } from '../dist/client.js';
+import { AgileMonsterClient, MCP_SERVER_VERSION } from '../dist/client.js';
 
 const cliCommands = new Set([
   'bootstrap',
@@ -30,7 +30,31 @@ if (firstArg === '--version' || firstArg === '-v' || firstArg === 'version') {
   await ensureUserPath();
   forgetEngineReadiness();
   console.log(await describeAgents());
+  const { describeService } = await import('../dist/service.js');
+  console.log(`\n${await describeService()}`);
   process.exit(0);
+} else if (firstArg === 'service') {
+  // The background runner that works cards with no coding tool open: install | status | uninstall
+  const { installService, uninstallService, describeService } = await import('../dist/service.js');
+  const { ensureUserPath } = await import('../dist/runtime.js');
+  await ensureUserPath();
+  const sub = process.argv[3] || 'status';
+  const force = process.argv.includes('--force');
+  if (sub === 'install') {
+    const key = new AgileMonsterClient().getApiKey();
+    // The service is not started inside a project folder, so it reads the key from the home config
+    if (key && !AgileMonsterClient.hasGlobalApiKey()) AgileMonsterClient.saveGlobalConfig({ api_key: key });
+    const res = await installService({ force, hasApiKey: Boolean(key) });
+    console.log(res.message);
+    process.exit(res.ok ? 0 : 1);
+  } else if (sub === 'uninstall' || sub === 'remove') {
+    const res = await uninstallService({ force });
+    console.log(res.message);
+    process.exit(res.ok ? 0 : 1);
+  } else {
+    console.log(await describeService());
+    process.exit(0);
+  }
 } else if (firstArg === 'pulse-daemon' || firstArg === '--pulse-daemon') {
   runBackgroundPulseDaemon(20000).catch((err) => {
     console.error('Fatal Pulse Daemon Error:', err);

package/bin/orchestrator.js

@@ -38,6 +38,7 @@ async function main() {
         ide: ideArg,
         board: boardArg,
         provider: providerArg,
+        service: !args.includes('--no-service'),
       });
       break;
     }

package/dist/agent-engine.d.ts

@@ -48,6 +48,8 @@ export interface EngineStatus {
 export declare function engineStatuses(): Promise<EngineStatus[]>;
 /** What `agilemonster agents` prints: which agent works a queued card here, and the one step that would fix the others. */
 export declare function describeAgents(): Promise<string>;
+/** How this machine works cards: with real agents, with the developer's own command, or with agents switched off. */
+export declare function agentMode(): 'agents' | 'builtin' | 'custom';
 export declare function engineLabelFor(provider: string): string | null;
 /**
  * The agent CLIs this machine can run for a card, best first: the card's own agent, then any other one that
@@ -90,6 +92,8 @@ export interface AgentReport {
     summary: string;
     verificationSteps: string[];
     question: string;
+    /** Short answers the requester can pick with one tap, when the question has a few clear ones. */
+    options: string[];
 }
 /** Read the closing JSON object out of the agent's final message. Tolerates code fences and prose around it. */
 export declare function parseAgentReport(text: string): AgentReport;

package/dist/agent-engine.js

@@ -243,6 +243,15 @@ async function readiness(spec, bin) {
     readyCache.set(bin, { at: Date.now(), reason });
     return reason;
 }
+/** How this machine works cards: with real agents, with the developer's own command, or with agents switched off. */
+export function agentMode() {
+    const pinned = (process.env.AGILEMONSTER_AGENT_ENGINE || '').trim().toLowerCase();
+    if (['builtin', 'built-in', 'off', 'none', '0', 'false'].includes(pinned))
+        return 'builtin';
+    if (customCommand() && (!pinned || pinned === 'auto' || pinned === 'custom'))
+        return 'custom';
+    return 'agents';
+}
 export function engineLabelFor(provider) {
     const spec = ENGINES.find((e) => e.providers.includes((provider || '').toLowerCase()));
     return spec ? spec.label : null;
@@ -368,7 +377,7 @@ export function buildAgentPrompt(brief) {
         lines.push(`- An earlier attempt at this card left uncommitted changes in ${brief.earlierFiles.slice(0, 40).map((f) => `\`${f}\``).join(', ')}. They are yours to keep, fix or replace.` +
             (brief.earlierSummary ? ` It reported: ${brief.earlierSummary.trim().slice(0, 600)}` : ''));
     }
-    lines.push('', '## When you are done', 'End your reply with one JSON object on its own, and nothing after it:', '{"status":"done","summary":"2-4 plain sentences for the person reviewing the card: what changed and where they will see it","verification_steps":["a step they can do in the running app","..."]}', 'Only if the work is impossible or unsafe without something that is not in the repository:', '{"status":"blocked","question":"the one specific thing you need, and what you already tried"}');
+    lines.push('', '## When you are done', 'End your reply with one JSON object on its own, and nothing after it:', '{"status":"done","summary":"2-4 plain sentences for the person reviewing the card: what changed and where they will see it","verification_steps":["a step they can do in the running app","..."]}', 'Only if the work is impossible or unsafe without something that is not in the repository:', '{"status":"blocked","question":"the one specific thing you need, and what you already tried","options":["up to four short answers the requester can pick with one tap, if the question has clear ones"]}');
     return lines.join('\n');
 }
 /** Read the closing JSON object out of the agent's final message. Tolerates code fences and prose around it. */
@@ -395,13 +404,16 @@ export function parseAgentReport(text) {
                     summary: String(obj.summary || '').trim(),
                     verificationSteps: steps,
                     question: String(obj.question || '').trim(),
+                    options: Array.isArray(obj.options)
+                        ? obj.options.map((o) => String(o).trim()).filter((o) => o.length > 0 && o.length <= 80).slice(0, 4)
+                        : [],
                 };
             }
             catch { }
             end = clean.lastIndexOf('}', end - 1);
         }
     }
-    return { status: 'unknown', summary: '', verificationSteps: [], question: '' };
+    return { status: 'unknown', summary: '', verificationSteps: [], question: '', options: [] };
 }
 /** The agent's prose without the closing JSON object: what to show a human when the report is missing a field. */
 export function proseOf(text, maxChars = 900) {

package/dist/client.d.ts

@@ -1,5 +1,10 @@
+import type { MachineReport } from './machine.js';
 import { ActiveClaim, AgileMonsterProjectConfig, AutonomousStepResponse, CardComment, DeployReport, Board, BoardAgentConfig, Card, ContextResponse, DiscoveredProject, PulseResponse } from './types.js';
-export declare const MCP_SERVER_VERSION = "1.0.25";
+export declare const MCP_SERVER_VERSION = "1.0.26";
+export type QuestionOption = string | {
+    label: string;
+    reply: string;
+};
 /** An API call the server answered with an error status. `status` lets callers tell "refused" from "broken". */
 export declare class ApiError extends Error {
     readonly status: number;
@@ -22,6 +27,8 @@ export declare class AgileMonsterClient {
     setApiKey(key: string): void;
     loadProjectConfig(): AgileMonsterProjectConfig | null;
     saveProjectConfig(config: AgileMonsterProjectConfig, dir?: string): string;
+    /** True when ~/.agilemonster/config.json already holds a key (what a background service reads). */
+    static hasGlobalApiKey(): boolean;
     static saveGlobalConfig(data: {
         api_key?: string;
     }): string;
@@ -38,7 +45,8 @@ export declare class AgileMonsterClient {
         agents: BoardAgentConfig[];
     }>;
     pulse(options: {
-        boardId: string;
+        /** Omitted by a background service that was not started inside a project folder. */
+        boardId?: string;
         provider?: string;
         projectName?: string;
         projectPath?: string;
@@ -50,6 +58,8 @@ export declare class AgileMonsterClient {
         installedAgents?: string[];
         /** Cards this process holds: the server extends their claim (heartbeat). */
         activeClaims?: ActiveClaim[];
+        /** This computer and the agents on it that can take a card (shown on the board next to a waiting card). */
+        machine?: MachineReport;
     }): Promise<PulseResponse>;
     /** Extend the claims this process holds. Used while a long job keeps the pulse loop busy. */
     heartbeat(activeClaims: ActiveClaim[]): Promise<{
@@ -93,7 +103,11 @@ export declare class AgileMonsterClient {
         cards: Card[];
     }>;
     claimTask(cardId: string, provider: string, runRef?: string, expectedBoardId?: string): Promise<Card>;
-    askQuestion(cardId: string, provider: string, question: string): Promise<Card>;
+    /**
+     * `options` become reply buttons on the card: a plain string is both the button and the reply, a
+     * {label, reply} pair shows one thing and sends another ("Yes, deploy this way" -> "deploy: ./deploy.sh").
+     */
+    askQuestion(cardId: string, provider: string, question: string, options?: QuestionOption[]): Promise<Card>;
     addProgress(cardId: string, provider: string, update: string, tokensUsed?: number, costUsd?: number): Promise<Card>;
     recordSpend(cardId: string, provider: string, tokens: number, costUsd: number, note?: string): Promise<Card>;
     setBudget(cardId: string, maxBudgetUsd?: number | null, maxTokens?: number | null): Promise<Card>;

package/dist/client.js

@@ -4,7 +4,7 @@ import { execSync } from 'node:child_process';
 import { resolveDeployProfile } from './deploy-profile.js';
 import { loadMemory } from './deploy-memory.js';
 import { stripRemoteCredentials } from './redact.js';
-export const MCP_SERVER_VERSION = '1.0.25';
+export const MCP_SERVER_VERSION = '1.0.26';
 /** An API call the server answered with an error status. `status` lets callers tell "refused" from "broken". */
 export class ApiError extends Error {
     status;
@@ -111,6 +111,19 @@ export class AgileMonsterClient {
         this.cachedConfig = config;
         return configPath;
     }
+    /** True when ~/.agilemonster/config.json already holds a key (what a background service reads). */
+    static hasGlobalApiKey() {
+        try {
+            const homedir = process.env.HOME || process.env.USERPROFILE || '';
+            if (!homedir)
+                return false;
+            const parsed = JSON.parse(fs.readFileSync(path.join(homedir, '.agilemonster', 'config.json'), 'utf8'));
+            return typeof parsed?.api_key === 'string' && parsed.api_key.trim() !== '';
+        }
+        catch {
+            return false;
+        }
+    }
     static saveGlobalConfig(data) {
         const homedir = process.env.HOME || process.env.USERPROFILE || '';
         if (!homedir)
@@ -216,6 +229,7 @@ export class AgileMonsterClient {
                 discovered_models: options.discoveredModels,
                 installed_agents: installed,
                 active_claims: options.activeClaims && options.activeClaims.length > 0 ? options.activeClaims : undefined,
+                machine: options.machine,
             }),
         });
     }
@@ -453,11 +467,12 @@ export class AgileMonsterClient {
      */
     discoverLocalProjects() {
         const roots = new Set();
+        const homedir = process.env.HOME || process.env.USERPROFILE || '';
         const parentDir = path.dirname(this.cwd);
-        if (parentDir && parentDir !== '/' && parentDir !== this.cwd) {
+        // A background service runs from the home folder: its parent holds other people's homes, not projects
+        if (parentDir && parentDir !== '/' && parentDir !== this.cwd && path.resolve(this.cwd) !== path.resolve(homedir || '/')) {
             roots.add(parentDir);
         }
-        const homedir = process.env.HOME || process.env.USERPROFILE || '';
         if (homedir) {
             for (const sub of ['dev', 'Projects', 'Code', 'repos', 'Developer']) {
                 const candidate = path.join(homedir, sub);
@@ -555,10 +570,14 @@ export class AgileMonsterClient {
             body: JSON.stringify({ provider, run_ref: runRef, board_id: boardId }),
         });
     }
-    async askQuestion(cardId, provider, question) {
+    /**
+     * `options` become reply buttons on the card: a plain string is both the button and the reply, a
+     * {label, reply} pair shows one thing and sends another ("Yes, deploy this way" -> "deploy: ./deploy.sh").
+     */
+    async askQuestion(cardId, provider, question, options) {
         return this.request(`/api/agent/cards/${cardId}/ask-question`, {
             method: 'POST',
-            body: JSON.stringify({ provider, question }),
+            body: JSON.stringify({ provider, question, options: options && options.length > 0 ? options.slice(0, 4) : undefined }),
         });
     }
     async addProgress(cardId, provider, update, tokensUsed, costUsd) {

package/dist/machine.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What this computer tells the board with every pulse: which machine it is, whether the runner is the
+ * background service or a coding tool that happens to be open, and which agents on it can take a card.
+ * The board turns that into what a person reads next to a waiting card ("Codex on Studio Mac is ready",
+ * "Cursor is not signed in").
+ */
+export interface MachineReport {
+    id: string;
+    name: string;
+    platform: string;
+    runner: 'service' | 'ide';
+    mode: 'agents' | 'builtin' | 'custom';
+    agents: Array<{
+        id: string;
+        label: string;
+        ready: boolean;
+        problem: string | null;
+    }>;
+}
+/** A stable id for this computer, made once and kept in ~/.agilemonster/machine.json. */
+export declare function machineIdentity(): {
+    id: string;
+    name: string;
+};
+export declare function machineReport(role: 'daemon' | 'stdio'): Promise<MachineReport>;

package/dist/machine.js

@@ -0,0 +1,32 @@
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { agentMode, engineStatuses } from './agent-engine.js';
+import { agileMonsterHome, readJson, writeJsonAtomic } from './runtime.js';
+/** A stable id for this computer, made once and kept in ~/.agilemonster/machine.json. */
+export function machineIdentity() {
+    const file = path.join(agileMonsterHome(), 'machine.json');
+    const saved = readJson(file);
+    let id = typeof saved?.id === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(saved.id) ? saved.id : '';
+    if (!id) {
+        id = crypto.randomUUID();
+        try {
+            writeJsonAtomic(file, { id });
+        }
+        catch { }
+    }
+    const name = (os.hostname() || 'computer').replace(/\.(local|lan|home|localdomain)$/i, '').slice(0, 120);
+    return { id, name };
+}
+export async function machineReport(role) {
+    const { id, name } = machineIdentity();
+    const agents = await engineStatuses();
+    return {
+        id,
+        name,
+        platform: process.platform,
+        runner: role === 'daemon' ? 'service' : 'ide',
+        mode: agentMode(),
+        agents: agents.map((a) => ({ id: a.id, label: a.label, ready: !a.problem, problem: a.problem })),
+    };
+}

package/dist/orchestrator.d.ts

@@ -21,6 +21,8 @@ export declare class AgileMonsterOrchestrator {
         provider?: string;
         ide?: string;
         board?: string;
+        /** False skips installing the background runner (`--no-service`). */
+        service?: boolean;
     }): Promise<void>;
     bootstrapInteractive(options?: {
         provider?: string;

package/dist/orchestrator.js

@@ -6,6 +6,9 @@ import { AGENT_GUIDELINES_MARKDOWN } from './guidelines.js';
 import { configureIdeTargets } from './ide-config.js';
 import { ensureLocalGitExcludes } from './deploy-runner.js';
 import { stripRemoteCredentials } from './redact.js';
+import { describeAgents } from './agent-engine.js';
+import { ensureUserPath } from './runtime.js';
+import { installService } from './service.js';
 export class AgileMonsterOrchestrator {
     client;
     constructor(client = new AgileMonsterClient()) {
@@ -313,15 +316,38 @@ export class AgileMonsterOrchestrator {
         // Configure IDEs (Cursor, Claude Code, Windsurf, Antigravity, VS Code)
         this.configureIdes(apiKey, options?.ide || options?.provider);
         this.ensureGitignore();
-        console.log('\n🎉 Project successfully connected to Agile Monster!');
+        // The background runner: without it cards are only worked while a coding tool is open in this folder
+        let background = false;
+        if (options?.service !== false && process.env.AGILEMONSTER_NO_SERVICE !== '1') {
+            console.log('\n⚙️  Setting up the background runner, so cards are worked with no coding tool open...');
+            try {
+                await ensureUserPath();
+                // The service is not started inside a project folder, so it reads the key from the home config
+                if (!AgileMonsterClient.hasGlobalApiKey())
+                    AgileMonsterClient.saveGlobalConfig({ api_key: apiKey });
+                const svc = await installService({ hasApiKey: true });
+                background = svc.outcome === 'installed' || svc.outcome === 'kept';
+                console.log(`${svc.ok ? '✅' : '⚠️ '} ${svc.message}`);
+            }
+            catch (err) {
+                console.log(`⚠️  The background runner could not be set up: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Which coding agent will actually do the work, and the one step that fixes one that is not ready
+        try {
+            console.log(`\n${await describeAgents()}`);
+        }
+        catch { }
+        console.log('\n🎉 This folder is connected to Agile Monster.');
         console.log('\n======================================================');
-        console.log('               🚀 HOW TO USE IT NOW                   ');
+        console.log('               🚀 WHAT HAPPENS NOW                    ');
         console.log('======================================================');
-        console.log(`1. Open board "${targetBoard.name}" on https://app.agilemonster.com`);
-        console.log(`2. Open any card and assign Worker to "${shortTag ? `Cursor-${shortTag}` : `Cursor: ${targetBoard.name}`}" (or Claude Code / Antigravity).`);
-        console.log('3. In your AI IDE chat inside this project, simply say:');
-        console.log('     "Check my Agile Monster tasks and start the next queued card."');
-        console.log('   Or connect another project folder (e.g. Planogram.ai in Cursor) anytime by running:');
+        console.log(`1. Open the board "${targetBoard.name}" on https://app.agilemonster.com`);
+        console.log(`2. Add a card that says what you want, open it, and under "Assign to AI Agent or Team Member" choose "${shortTag ? `Cursor-${shortTag}` : `Cursor: ${targetBoard.name}`}" (or another agent).`);
+        console.log(background
+            ? '3. That is all. The card is picked up within about 20 seconds, worked in this folder, and comes back to you for review.'
+            : '3. Keep your AI coding tool open in this folder: the card is picked up within about 20 seconds while it is open, and comes back to you for review.');
+        console.log('\nTo connect another project folder, run the same command there:');
         console.log('     cd /path/to/other-project && npx -y @agilemonster/mcp-server bootstrap\n');
     }
     async bootstrapInteractive(options) {

package/dist/server.d.ts

@@ -1,7 +1,16 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { AgileMonsterClient } from './client.js';
+import { AgileMonsterClient, QuestionOption } from './client.js';
 import { ActiveClaim, Card } from './types.js';
 import { BoundProfile } from './deploy-profile.js';
+/**
+ * The answers a deploy question accepts, as reply buttons: nobody should have to type `deploy: ./deploy.sh`.
+ * A first-time route gets "yes, this way" and "I deploy it myself"; a failure gets "try again".
+ */
+export declare function deployReplyOptions(res: {
+    errorKind?: string | null;
+    method?: string | null;
+    command?: string | null;
+}): QuestionOption[];
 export declare function createServer(client?: AgileMonsterClient): Server<{
     method: string;
     params?: {

package/dist/server.js

@@ -8,6 +8,8 @@ import { spawn, execSync, execFileSync } from 'node:child_process';
 import { isUtf8 } from 'node:buffer';
 import { fileURLToPath } from 'node:url';
 import { AgileMonsterClient, MCP_SERVER_VERSION, isClaimConflict } from './client.js';
+import { machineReport } from './machine.js';
+import { managedRunnerDir, updateArgs } from './service.js';
 import { AGENT_GUIDELINES_MARKDOWN } from './guidelines.js';
 import { knownSecrets, redactResult } from './redact.js';
 import { describeProfile, methodLabel, normalizeMethod, resolveDeployProfile, trustBoundRoute, } from './deploy-profile.js';
@@ -15,6 +17,21 @@ import { addPendingVerification, getCardState, loadMemory, recordAttempt, remove
 import { checkCiOnce, describeFailureForHuman, ensureLocalGitExcludes, parseDeployDirective, runDeployment, } from './deploy-runner.js';
 import { baselineFor, buildAgentPrompt, changesSince, clearBaseline, engineLabelFor, engineStatuses, markNewFilesForDiff, parseAgentReport, proseOf, resolveEngines, restoreWorkingTree, runEngine, } from './agent-engine.js';
 import { addWellKnownToolDirs, agileMonsterHome, configureLogger, ensureUserPath, errorMessage, exec, log, readJson, which, writeJsonAtomic, } from './runtime.js';
+/**
+ * The answers a deploy question accepts, as reply buttons: nobody should have to type `deploy: ./deploy.sh`.
+ * A first-time route gets "yes, this way" and "I deploy it myself"; a failure gets "try again".
+ */
+export function deployReplyOptions(res) {
+    if (res.errorKind === 'needs_confirmation') {
+        const route = (res.command || res.method || '').trim();
+        const options = [];
+        if (route)
+            options.push({ label: 'Yes, deploy this way', reply: `deploy: ${route}` });
+        options.push({ label: 'I deploy it myself', reply: 'deploy: manual' });
+        return options;
+    }
+    return [{ label: 'Try again', reply: 'retry' }];
+}
 export function createServer(client = new AgileMonsterClient()) {
     const server = new Server({
         name: 'agilemonster-mcp-server',
@@ -263,6 +280,11 @@ Please strictly follow the Agile Monster Task Lifecycle Protocol:
                         type: 'string',
                         description: 'The question for the user.',
                     },
+                    options: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Optional: up to four short answers the user can pick with one tap. The card shows them as buttons, and the user can still type a different answer.',
+                    },
                 },
                 required: ['card_id', 'provider', 'question'],
             },
@@ -640,7 +662,10 @@ Please strictly follow the Agile Monster Task Lifecycle Protocol:
                     const cardId = args.card_id;
                     const provider = args.provider || projectConfig?.provider || 'antigravity';
                     const question = args.question;
-                    const card = await client.askQuestion(cardId, provider, question);
+                    const answers = Array.isArray(args.options)
+                        ? args.options.map((o) => String(o).trim()).filter((o) => o.length > 0 && o.length <= 80).slice(0, 4)
+                        : [];
+                    const card = await client.askQuestion(cardId, provider, question, answers);
                     releaseClaim(cardId);
                     return {
                         content: [
@@ -1015,11 +1040,16 @@ function triggerBackgroundSelfUpdate(targetVersion) {
                 catch { }
             }
         }
-        // 2. Install @agilemonster/mcp-server@latest into global/npx cache, then exit once idle so launchd respawns the daemon
-        const child = spawn('sh', ['-c', 'npm install -g @agilemonster/mcp-server@latest >/dev/null 2>&1 || npx -y @agilemonster/mcp-server@latest --version >/dev/null 2>&1'], {
-            stdio: 'ignore',
-            detached: true,
-        });
+        // 2. Fetch the new version, then exit once idle so launchd/systemd starts it. The background service
+        // updates its own copy in place; a runner started any other way refreshes the global install / npx cache.
+        const ownDir = managedRunnerDir(fileURLToPath(import.meta.url));
+        const npm = which('npm');
+        const child = ownDir && npm
+            ? spawn(npm, updateArgs(ownDir), { stdio: 'ignore', detached: true, cwd: ownDir })
+            : spawn('sh', ['-c', 'npm install -g @agilemonster/mcp-server@latest >/dev/null 2>&1 || npx -y @agilemonster/mcp-server@latest --version >/dev/null 2>&1'], {
+                stdio: 'ignore',
+                detached: true,
+            });
         child.on('exit', () => {
             appendIdeActivityLog(cwd, {
                 cardId: 'system-update',
@@ -1579,7 +1609,7 @@ async function runRedeployOnlyCard(client, card, projectPath, provider, workerLa
             pending_confirmation: res.errorKind === 'needs_confirmation' ? { method: res.method, command: res.command } : null,
         }));
         removeTaskLock(lockFile);
-        await client.askQuestion(card.id, provider, res.errorKind === 'needs_confirmation' ? describeFailureForHuman(res) : `The redeploy did not go through.\n\n${describeFailureForHuman(res)}`);
+        await client.askQuestion(card.id, provider, res.errorKind === 'needs_confirmation' ? describeFailureForHuman(res) : `The redeploy did not go through.\n\n${describeFailureForHuman(res)}`, deployReplyOptions(res));
         return false;
     }
     if (res.pending && res.pendingVerification)
@@ -1683,7 +1713,7 @@ async function resumeFailedDeployment(client, card, projectPath, provider, worke
         // Nothing is ever confirmed on the human's behalf.
         removeTaskLock(lockFile);
         setCardState(projectPath, card.id, { ...state, at: new Date().toISOString() });
-        await client.askQuestion(card.id, provider, `I still need an answer before I deploy this project for the first time. Reply \`deploy: ${pendingRoute.command || pendingRoute.method}\` to confirm, \`deploy: manual\` if you deploy it yourself, or tell me the right route.`);
+        await client.askQuestion(card.id, provider, `I still need an answer before I deploy this project for the first time. Reply \`deploy: ${pendingRoute.command || pendingRoute.method}\` to confirm, \`deploy: manual\` if you deploy it yourself, or tell me the right route.`, deployReplyOptions({ errorKind: 'needs_confirmation', method: pendingRoute.method, command: pendingRoute.command }));
         return 'failed';
     }
     // No fresh reply at all: a re-queue of a deploy-failed card means "try the same deployment again".
@@ -1736,7 +1766,7 @@ async function resumeFailedDeployment(client, card, projectPath, provider, worke
         });
         await client.askQuestion(card.id, provider, res.errorKind === 'needs_confirmation'
             ? describeFailureForHuman(res)
-            : `The deployment still did not go through, so this card stays in progress.\n\n${describeFailureForHuman(res)}`);
+            : `The deployment still did not go through, so this card stays in progress.\n\n${describeFailureForHuman(res)}`, deployReplyOptions(res));
         return 'failed';
     }
     if (res.pending && res.pendingVerification) {
@@ -1904,7 +1934,7 @@ async function produceChangeWithAgent(run) {
         return files.length > 0;
     };
     run.rollback.fn = async () => revert((await changesSince(projectPath, baseline)).changed);
-    const backToHuman = async (question, summary, files) => {
+    const backToHuman = async (question, summary, files, options = []) => {
         run.rollback.fn = null;
         removeTaskLock(lockFile);
         appendIdeActivityLog(projectPath, {
@@ -1916,9 +1946,10 @@ async function produceChangeWithAgent(run) {
             summary,
             files,
         });
-        await client.askQuestion(card.id, provider, question);
+        await client.askQuestion(card.id, provider, question, options);
         return 'handled';
     };
+    const TRY_AGAIN = [{ label: 'Try again', reply: 'Please try again.' }];
     const prompt = buildAgentPrompt({
         title: card.title || '',
         description: card.description || '',
@@ -1974,11 +2005,11 @@ async function produceChangeWithAgent(run) {
         await revert(change.changed);
         return backToHuman(`I need to change ${foreign.map((f) => `\`${f}\``).join(', ')}, but ${foreign.length === 1 ? 'that file has' : 'those files have'} uncommitted changes in \`${projectPath}\` that are not mine. Committing my edit would also commit that unfinished work, so I stopped and put everything back.\n\n${started.interrupted
             ? 'An earlier run of this card was interrupted before it finished, so these may be its leftovers rather than your work. If you did not make them, discard them (`git checkout -- <file>`); otherwise commit or stash them. Then reply here and I will continue.'
-            : 'Commit or stash those changes, then reply here and I will continue.'}`, `Stopped: ${foreign.join(', ')} had uncommitted changes`, foreign);
+            : 'Commit or stash those changes, then reply here and I will continue.'}`, `Stopped: ${foreign.join(', ')} had uncommitted changes`, foreign, [{ label: 'Done, continue', reply: 'I committed or stashed those changes. Please continue.' }]);
     }
     if (!result.ok) {
         await revert(change.changed);
-        return backToHuman(`${engine.label} worked on this for ${Math.max(1, Math.round(result.durationMs / 60000))} minute(s) but did not finish: ${result.failure || 'it stopped without a result'}.\n\nI put the files back the way they were. Reply here to have it try again — if the card is large, splitting it into smaller cards helps.`, `${engine.label} did not finish: ${result.failure || 'no result'}`, []);
+        return backToHuman(`${engine.label} worked on this for ${Math.max(1, Math.round(result.durationMs / 60000))} minute(s) but did not finish: ${result.failure || 'it stopped without a result'}.\n\nI put the files back the way they were. Reply here to have it try again — if the card is large, splitting it into smaller cards helps.`, `${engine.label} did not finish: ${result.failure || 'no result'}`, [], TRY_AGAIN);
     }
     let report = parseAgentReport(result.text);
     if (report.status === 'blocked' || change.changed.length === 0) {
@@ -1986,7 +2017,7 @@ async function produceChangeWithAgent(run) {
         const said = report.question || report.summary || proseOf(result.text);
         return backToHuman(report.status === 'blocked' && report.question
             ? report.question
-            : `${engine.label} finished without changing any files.${said ? `\n\n${said}` : ''}\n\nIf something is still missing, reply here with what you expected to change.`, `Needs input: ${said.slice(0, 400)}`, []);
+            : `${engine.label} finished without changing any files.${said ? `\n\n${said}` : ''}\n\nIf something is still missing, reply here with what you expected to change.`, `Needs input: ${said.slice(0, 400)}`, [], report.status === 'blocked' && report.question ? report.options : []);
     }
     // 2. The runner's own build gate. The agent built it too, so a failure here is usually this machine's
     // environment — check that before sending the agent after an error that was never its own.
@@ -2032,7 +2063,7 @@ async function produceChangeWithAgent(run) {
             const stillForeign = change.overlapping.filter((f) => !carryOverFiles.includes(f));
             if (!gate.ok || change.changed.length === 0 || stillForeign.length > 0) {
                 await revert(change.changed);
-                return backToHuman(`${engine.label} made the change, but the project did not build with it, and its attempt to fix that did not get the build green. I reverted everything rather than ship a broken build.\n\n\`\`\`\n${buildErrorExcerpt(gate.errorOutput || '')}\n\`\`\`\n\nYour description was clear — nothing more is needed from you on that. Reply here to have it try again.`, `Reverted: the build failed after ${engine.label}'s change`, []);
+                return backToHuman(`${engine.label} made the change, but the project did not build with it, and its attempt to fix that did not get the build green. I reverted everything rather than ship a broken build.\n\n\`\`\`\n${buildErrorExcerpt(gate.errorOutput || '')}\n\`\`\`\n\nYour description was clear — nothing more is needed from you on that. Reply here to have it try again.`, `Reverted: the build failed after ${engine.label}'s change`, [], TRY_AGAIN);
             }
         }
     }
@@ -2505,7 +2536,7 @@ export async function executeQueuedCardAutonomously(client, card, projectPath) {
                 const changed = modifiedFiles.map((f) => `\`${f}\``).join(', ');
                 await client.askQuestion(card.id, provider, deployInfo.errorKind === 'needs_confirmation'
                     ? `I made the code change (${changed}). One question before I deploy this project for the first time:\n\n${describeFailureForHuman(deployInfo)}`
-                    : `I made the code change (${changed}), but the deployment could not be verified, so I kept this card in progress instead of moving it to Testing.\n\n${describeFailureForHuman(deployInfo)}`);
+                    : `I made the code change (${changed}), but the deployment could not be verified, so I kept this card in progress instead of moving it to Testing.\n\n${describeFailureForHuman(deployInfo)}`, deployReplyOptions(deployInfo));
                 return false;
             }
             if (deployInfo.pending && deployInfo.pendingVerification) {
@@ -2820,7 +2851,7 @@ async function processPendingVerifications(client, projectPaths) {
                         attempts: 1,
                         last_error: detail,
                     });
-                    await client.askQuestion(p.card_id, p.provider, `The deployment I started for this card did not succeed, so the change is NOT live yet.\n\nWhat failed: ${detail}\n\nFix the failing step and reply **retry**, or tell me the right route with \`deploy: <method or command>\`.`);
+                    await client.askQuestion(p.card_id, p.provider, `The deployment I started for this card did not succeed, so the change is NOT live yet.\n\nWhat failed: ${detail}\n\nFix the failing step and reply **retry**, or tell me the right route with \`deploy: <method or command>\`.`, deployReplyOptions({ errorKind: 'ci_failed' }));
                     await client.reportDeployment({ card_id: p.card_id, project_path: projectPath, method: 'github_actions', ok: false, error: detail.slice(0, 480), error_kind: 'ci_failed', commit: short });
                 }
                 else if (ageMs > 90 * 60 * 1000) {
@@ -2887,6 +2918,7 @@ export function startBuiltInPullPulse(server, client, intervalMs = 20000, role =
     let holdsWorkerLock = false;
     let journalsRecovered = false;
     let consecutiveFailures = 0;
+    let warnedNoKey = false;
     const autoProvisionSavedBindings = (apiKey, bindings) => {
         for (const b of bindings) {
             const projPath = (b.project_path || '').trim();
@@ -2965,19 +2997,28 @@ export function startBuiltInPullPulse(server, client, intervalMs = 20000, role =
         try {
             const config = client.loadProjectConfig();
             const apiKey = client.getApiKey();
-            if (!config?.board_id || !apiKey) {
+            // The background service is not started inside a project folder: it has no board of its own and
+            // serves every folder linked on this machine. A coding tool's MCP server only pulses for its project.
+            const homeBoardId = config?.board_id || '';
+            if (!apiKey || (!homeBoardId && role !== 'daemon')) {
+                if (role === 'daemon' && !apiKey && !warnedNoKey) {
+                    warnedNoKey = true;
+                    log.warn('daemon.no_api_key', { hint: 'run `npx -y @agilemonster/mcp-server bootstrap` in a project folder' });
+                }
                 return;
             }
+            const homePath = homeBoardId ? config?.project_path || process.cwd() : '';
             const includeDiscovery = pulseCount === 0 || pulseCount % 3 === 0;
             pulseCount++;
             const res = await client.pulse({
-                boardId: config.board_id,
+                boardId: homeBoardId || undefined,
                 provider: 'any',
-                projectName: config.project_name || path.basename(process.cwd()),
-                projectPath: config.project_path || process.cwd(),
+                projectName: homeBoardId ? config?.project_name || path.basename(process.cwd()) : undefined,
+                projectPath: homePath || undefined,
                 discoveredProjects: includeDiscovery ? client.discoverLocalProjects() : undefined,
                 discoveredModels: includeDiscovery ? client.discoverLocalAgentModels() : undefined,
                 activeClaims: activeClaims(),
+                machine: await machineReport(role).catch(() => undefined),
             });
             if (consecutiveFailures > 0) {
                 log.info('pulse.recovered', { after_failures: consecutiveFailures });
@@ -2987,13 +3028,14 @@ export function startBuiltInPullPulse(server, client, intervalMs = 20000, role =
                 autoProvisionSavedBindings(apiKey, res.saved_bindings);
             }
             const queued = res.queued_cards || [];
-            syncIdeTaskRules(config.board_name || 'Board', queued);
+            if (homeBoardId)
+                syncIdeTaskRules(config?.board_name || 'Board', queued);
             for (const card of queued) {
                 if (!notifiedCardIds.has(card.id)) {
                     notifiedCardIds.add(card.id);
                     const worker = card.agent_display_name || card.agent_provider || 'AI Agent';
                     const modelTag = card.agent_model && card.agent_model !== 'auto' ? ` [${card.agent_model}]` : '';
-                    sendDesktopNotification(`Agile Monster -> ${worker}${modelTag}`, `New task queued on ${config.board_name || 'Board'}: "${card.title}"`);
+                    sendDesktopNotification(`Agile Monster -> ${worker}${modelTag}`, `New task queued on ${config?.board_name || 'Board'}: "${card.title}"`);
                     try {
                         if (server) {
                             await server.sendResourceUpdated({ uri: 'agilemonster://project/context' });
@@ -3013,7 +3055,7 @@ export function startBuiltInPullPulse(server, client, intervalMs = 20000, role =
                 const boundQueued = res.all_bound_queued_cards || [];
                 for (const qCard of boundQueued) {
                     const targetPath = (qCard.bound_project_path || '').trim() ||
-                        (qCard.board_id === config.board_id ? config.project_path || process.cwd() : '');
+                        (homeBoardId && qCard.board_id === homeBoardId ? homePath : '');
                     if (targetPath && fs.existsSync(targetPath)) {
                         await executeQueuedCardAutonomously(client, qCard, targetPath);
                     }
@@ -3024,12 +3066,12 @@ export function startBuiltInPullPulse(server, client, intervalMs = 20000, role =
                 const boundDone = res.all_bound_done_cards || [];
                 for (const dCard of boundDone) {
                     const targetPath = (dCard.bound_project_path || '').trim() ||
-                        (dCard.board_id === config.board_id ? config.project_path || process.cwd() : '');
+                        (homeBoardId && dCard.board_id === homeBoardId ? homePath : '');
                     if (targetPath && fs.existsSync(targetPath)) {
                         await deployApprovedCardIfNeeded(client, dCard, targetPath);
                     }
                 }
-                const knownPaths = new Set([config.project_path || process.cwd()]);
+                const knownPaths = new Set(homePath ? [homePath] : []);
                 for (const b of res.saved_bindings || []) {
                     if (b.project_path)
                         knownPaths.add(b.project_path.trim());

package/dist/service.d.ts

@@ -0,0 +1,82 @@
+import { ExecOptions, ExecResult } from './runtime.js';
+/**
+ * Runs the card runner as a background service that starts with the computer.
+ *
+ * Without this, cards queued from the board are only worked while an AI coding tool happens to be open in
+ * the project folder (its MCP server pulses as a side effect). People do not know that, so their first card
+ * sits in "queued" for ever. `bootstrap` installs the service; `service install|status|uninstall` manage it.
+ *
+ * The service runs its own copy of the package from ~/.agilemonster/runner, so it does not depend on an npx
+ * cache that can be cleared or on a project folder that can move, and it updates that copy itself.
+ *
+ * macOS: a launchd agent. Linux: a systemd user unit. Windows: not yet.
+ */
+export declare const SERVICE_LABEL = "com.agilemonster.pulse";
+export declare const SYSTEMD_UNIT = "agilemonster-runner.service";
+export type ServiceKind = 'launchd' | 'systemd';
+export interface ServiceDeps {
+    platform: NodeJS.Platform;
+    home: string;
+    /** Machine-local Agile Monster folder (~/.agilemonster). */
+    amHome: string;
+    uid: number | null;
+    node: string;
+    npm: string | null;
+    pathEnv: string;
+    exec: (command: string, args?: string[], options?: ExecOptions) => Promise<ExecResult>;
+}
+/**
+ * The node binary the service should start. `process.execPath` is often a versioned folder (Homebrew's
+ * Cellar/node@24/24.21.0_1/…) that disappears with the next upgrade and would leave the service unable to
+ * start; the `node` on PATH is a stable link to the same binary, so prefer it when it is the same one.
+ */
+export declare function stableNodePath(): string;
+export declare function defaultServiceDeps(): ServiceDeps;
+export declare function runnerDir(amHome: string): string;
+/** The service's own copy of this package's entry point. */
+export declare function runnerEntry(amHome: string): string;
+export declare function serviceKind(platform: NodeJS.Platform): ServiceKind | null;
+export declare function unitPath(kind: ServiceKind, home: string): string;
+export interface UnitOptions {
+    node: string;
+    entry: string;
+    home: string;
+    logDir: string;
+    pathEnv: string;
+}
+export declare function launchdPlist(o: UnitOptions): string;
+export declare function systemdUnit(o: UnitOptions): string;
+/** The program an existing unit file starts (the script after the node binary), or null when unreadable. */
+export declare function unitTarget(kind: ServiceKind, content: string): string | null;
+export interface ServiceStatus {
+    supported: boolean;
+    kind: ServiceKind | null;
+    unitPath: string | null;
+    installed: boolean;
+    /** True when the unit starts the copy this module installs (not a hand-made or development setup). */
+    managed: boolean;
+    target: string | null;
+    running: boolean;
+}
+export declare function serviceStatus(deps?: ServiceDeps): Promise<ServiceStatus>;
+export interface ServiceResult {
+    ok: boolean;
+    /** 'installed' | 'kept' (someone else's setup left alone) | 'unsupported' | 'failed' | 'removed' | 'absent' */
+    outcome: 'installed' | 'kept' | 'unsupported' | 'failed' | 'removed' | 'absent';
+    message: string;
+}
+export declare function installService(options: {
+    force?: boolean;
+    hasApiKey: boolean;
+}, deps?: ServiceDeps): Promise<ServiceResult>;
+export declare function uninstallService(options?: {
+    force?: boolean;
+}, deps?: ServiceDeps): Promise<ServiceResult>;
+/** npm arguments that install or update the service's own copy of the package. */
+export declare function updateArgs(dir: string, version?: string): string[];
+/**
+ * When this process is the service's own copy, the folder to update in place. Null for a copy started by
+ * npx, a global install or a source checkout: those update the way they were installed.
+ */
+export declare function managedRunnerDir(runningFile: string, amHome?: string): string | null;
+export declare function describeService(deps?: ServiceDeps): Promise<string>;

package/dist/service.js

@@ -0,0 +1,327 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agileMonsterHome, exec, which } from './runtime.js';
+/**
+ * Runs the card runner as a background service that starts with the computer.
+ *
+ * Without this, cards queued from the board are only worked while an AI coding tool happens to be open in
+ * the project folder (its MCP server pulses as a side effect). People do not know that, so their first card
+ * sits in "queued" for ever. `bootstrap` installs the service; `service install|status|uninstall` manage it.
+ *
+ * The service runs its own copy of the package from ~/.agilemonster/runner, so it does not depend on an npx
+ * cache that can be cleared or on a project folder that can move, and it updates that copy itself.
+ *
+ * macOS: a launchd agent. Linux: a systemd user unit. Windows: not yet.
+ */
+export const SERVICE_LABEL = 'com.agilemonster.pulse';
+export const SYSTEMD_UNIT = 'agilemonster-runner.service';
+const PACKAGE = '@agilemonster/mcp-server';
+/**
+ * The node binary the service should start. `process.execPath` is often a versioned folder (Homebrew's
+ * Cellar/node@24/24.21.0_1/…) that disappears with the next upgrade and would leave the service unable to
+ * start; the `node` on PATH is a stable link to the same binary, so prefer it when it is the same one.
+ */
+export function stableNodePath() {
+    const onPath = which('node');
+    if (onPath) {
+        try {
+            if (fs.realpathSync(onPath) === fs.realpathSync(process.execPath))
+                return onPath;
+        }
+        catch { }
+    }
+    return process.execPath;
+}
+export function defaultServiceDeps() {
+    return {
+        platform: process.platform,
+        home: os.homedir(),
+        amHome: agileMonsterHome(),
+        uid: typeof process.getuid === 'function' ? process.getuid() : null,
+        node: stableNodePath(),
+        npm: which('npm'),
+        pathEnv: process.env.PATH || '',
+        exec,
+    };
+}
+export function runnerDir(amHome) {
+    return path.join(amHome, 'runner');
+}
+/** The service's own copy of this package's entry point. */
+export function runnerEntry(amHome) {
+    return path.join(runnerDir(amHome), 'node_modules', '@agilemonster', 'mcp-server', 'bin', 'mcp.js');
+}
+export function serviceKind(platform) {
+    if (platform === 'darwin')
+        return 'launchd';
+    if (platform === 'linux')
+        return 'systemd';
+    return null;
+}
+export function unitPath(kind, home) {
+    return kind === 'launchd'
+        ? path.join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`)
+        : path.join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT);
+}
+function xml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function launchdPlist(o) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(o.node)}</string>
+    <string>${xml(o.entry)}</string>
+    <string>pulse-daemon</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(o.home)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${xml(o.home)}</string>
+    <key>PATH</key>
+    <string>${xml(o.pathEnv)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>15</integer>
+  <key>StandardOutPath</key>
+  <string>${xml(path.join(o.logDir, 'pulse-daemon.log'))}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(path.join(o.logDir, 'pulse-daemon.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+/** systemd splits ExecStart on spaces; a path with one must be quoted, and a literal % doubled. */
+function systemdArg(value) {
+    const escaped = value.replace(/%/g, '%%').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return /[\s"']/.test(value) ? `"${escaped}"` : escaped;
+}
+export function systemdUnit(o) {
+    return `[Unit]
+Description=Agile Monster card runner
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=${systemdArg(o.node)} ${systemdArg(o.entry)} pulse-daemon
+WorkingDirectory=${o.home}
+Environment=${systemdArg(`PATH=${o.pathEnv}`)}
+Restart=always
+RestartSec=15
+StandardOutput=append:${path.join(o.logDir, 'pulse-daemon.log')}
+StandardError=append:${path.join(o.logDir, 'pulse-daemon.err.log')}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** The program an existing unit file starts (the script after the node binary), or null when unreadable. */
+export function unitTarget(kind, content) {
+    if (kind === 'launchd') {
+        const block = content.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+        if (!block)
+            return null;
+        const args = Array.from(block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)).map((m) => m[1].replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&'));
+        return args.find((a) => /mcp\.js$/.test(a)) || args[1] || args[0] || null;
+    }
+    const line = content.match(/^ExecStart=(.*)$/m);
+    if (!line)
+        return null;
+    const parts = line[1].match(/"(?:[^"\\]|\\.)*"|\S+/g) || [];
+    const clean = parts.map((p) => (p.startsWith('"') ? p.slice(1, -1).replace(/\\(["\\])/g, '$1') : p).replace(/%%/g, '%'));
+    return clean.find((a) => /mcp\.js$/.test(a)) || clean[1] || clean[0] || null;
+}
+export async function serviceStatus(deps = defaultServiceDeps()) {
+    const kind = serviceKind(deps.platform);
+    if (!kind)
+        return { supported: false, kind: null, unitPath: null, installed: false, managed: false, target: null, running: false };
+    const file = unitPath(kind, deps.home);
+    let content = '';
+    try {
+        content = fs.readFileSync(file, 'utf8');
+    }
+    catch { }
+    const installed = content !== '';
+    const target = installed ? unitTarget(kind, content) : null;
+    const managed = !!target && path.resolve(target) === path.resolve(runnerEntry(deps.amHome));
+    let running = false;
+    if (installed) {
+        if (kind === 'launchd') {
+            const res = deps.uid === null ? null : await deps.exec('launchctl', ['print', `gui/${deps.uid}/${SERVICE_LABEL}`], { timeoutMs: 15000 });
+            running = !!res && res.ok && /state = running/.test(res.stdout);
+        }
+        else {
+            const res = await deps.exec('systemctl', ['--user', 'is-active', SYSTEMD_UNIT], { timeoutMs: 15000 });
+            running = res.stdout.trim() === 'active';
+        }
+    }
+    return { supported: true, kind, unitPath: file, installed, managed, target, running };
+}
+const KEEP_OPEN_HINT = 'Until then, cards are worked while your AI coding tool is open in the project folder, or while this runs in a terminal: npx -y @agilemonster/mcp-server pulse-daemon';
+export async function installService(options, deps = defaultServiceDeps()) {
+    const kind = serviceKind(deps.platform);
+    if (!kind) {
+        return {
+            ok: false,
+            outcome: 'unsupported',
+            message: `The background runner cannot be installed as a service on this system yet (${deps.platform}). ${KEEP_OPEN_HINT}`,
+        };
+    }
+    if (!options.hasApiKey) {
+        return {
+            ok: false,
+            outcome: 'failed',
+            message: 'No API key is saved on this computer yet. Run `npx -y @agilemonster/mcp-server bootstrap` in your project folder first.',
+        };
+    }
+    const status = await serviceStatus(deps);
+    if (status.installed && !status.managed && !options.force) {
+        return {
+            ok: true,
+            outcome: 'kept',
+            message: `A background runner is already set up on this computer (${status.target || status.unitPath}), so it was left as it is.` +
+                ' To replace it with the standard one: npx -y @agilemonster/mcp-server service install --force',
+        };
+    }
+    if (!deps.npm) {
+        return { ok: false, outcome: 'failed', message: `npm was not found, so the runner could not be installed. ${KEEP_OPEN_HINT}` };
+    }
+    if (kind === 'systemd') {
+        const probe = await deps.exec('systemctl', ['--user', 'show-environment'], { timeoutMs: 15000 });
+        if (!probe.ok) {
+            return {
+                ok: false,
+                outcome: 'unsupported',
+                message: `This system has no systemd user session, so the background runner could not be installed as a service. ${KEEP_OPEN_HINT}`,
+            };
+        }
+    }
+    // 1. The service's own copy of the package
+    const dir = runnerDir(deps.amHome);
+    const entry = runnerEntry(deps.amHome);
+    const logDir = path.join(deps.amHome, 'logs');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.mkdirSync(logDir, { recursive: true });
+        const manifest = path.join(dir, 'package.json');
+        if (!fs.existsSync(manifest)) {
+            fs.writeFileSync(manifest, JSON.stringify({ name: 'agilemonster-runner', private: true }, null, 2), 'utf8');
+        }
+    }
+    catch (err) {
+        return { ok: false, outcome: 'failed', message: `Could not create ${dir}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const install = await deps.exec(deps.npm, updateArgs(dir), { cwd: dir, timeoutMs: 5 * 60 * 1000 });
+    if (!install.ok || !fs.existsSync(entry)) {
+        return { ok: false, outcome: 'failed', message: `Installing the runner failed: ${install.tail || 'npm did not produce the package'}. ${KEEP_OPEN_HINT}` };
+    }
+    // 2. The unit that starts it
+    const file = unitPath(kind, deps.home);
+    const unitOptions = { node: deps.node, entry, home: deps.home, logDir, pathEnv: deps.pathEnv };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, kind === 'launchd' ? launchdPlist(unitOptions) : systemdUnit(unitOptions), 'utf8');
+    }
+    catch (err) {
+        return { ok: false, outcome: 'failed', message: `Could not write ${file}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    // 3. Start it now and at every login
+    if (kind === 'launchd') {
+        if (deps.uid === null)
+            return { ok: false, outcome: 'failed', message: 'Could not determine the current user to start the service for.' };
+        const domain = `gui/${deps.uid}`;
+        await deps.exec('launchctl', ['bootout', `${domain}/${SERVICE_LABEL}`], { timeoutMs: 20000 }); // an older copy; fine if absent
+        let start = await deps.exec('launchctl', ['bootstrap', domain, file], { timeoutMs: 20000 });
+        if (!start.ok)
+            start = await deps.exec('launchctl', ['load', '-w', file], { timeoutMs: 20000 });
+        if (!start.ok) {
+            return { ok: false, outcome: 'failed', message: `The runner was installed but macOS would not start it: ${start.tail}. Log out and in again, or run: launchctl load -w "${file}"` };
+        }
+    }
+    else {
+        await deps.exec('systemctl', ['--user', 'daemon-reload'], { timeoutMs: 20000 });
+        const start = await deps.exec('systemctl', ['--user', 'enable', '--now', SYSTEMD_UNIT], { timeoutMs: 30000 });
+        if (!start.ok) {
+            return { ok: false, outcome: 'failed', message: `The runner was installed but systemd would not start it: ${start.tail}` };
+        }
+        // Keep it running when nobody is logged in at the desktop (best effort: needs no password on most systems)
+        const user = os.userInfo().username;
+        if (which('loginctl'))
+            await deps.exec('loginctl', ['enable-linger', user], { timeoutMs: 15000 });
+    }
+    return {
+        ok: true,
+        outcome: 'installed',
+        message: 'The background runner is installed and running. It starts with this computer and works cards queued from the board, with no coding tool open.',
+    };
+}
+export async function uninstallService(options = {}, deps = defaultServiceDeps()) {
+    const status = await serviceStatus(deps);
+    if (!status.supported || !status.kind || !status.unitPath) {
+        return { ok: false, outcome: 'unsupported', message: 'There is no background runner service on this system.' };
+    }
+    if (!status.installed)
+        return { ok: true, outcome: 'absent', message: 'No background runner service is installed.' };
+    if (!status.managed && !options.force) {
+        return {
+            ok: true,
+            outcome: 'kept',
+            message: `The runner service on this computer was not installed by this command (${status.target || status.unitPath}), so it was left as it is. Add --force to remove it anyway.`,
+        };
+    }
+    if (status.kind === 'launchd') {
+        if (deps.uid !== null)
+            await deps.exec('launchctl', ['bootout', `gui/${deps.uid}/${SERVICE_LABEL}`], { timeoutMs: 20000 });
+    }
+    else {
+        await deps.exec('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT], { timeoutMs: 30000 });
+    }
+    try {
+        fs.rmSync(status.unitPath, { force: true });
+        if (status.managed)
+            fs.rmSync(runnerDir(deps.amHome), { recursive: true, force: true });
+    }
+    catch (err) {
+        return { ok: false, outcome: 'failed', message: `Stopped the service but could not remove its files: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (status.kind === 'systemd')
+        await deps.exec('systemctl', ['--user', 'daemon-reload'], { timeoutMs: 20000 });
+    return { ok: true, outcome: 'removed', message: 'The background runner service was stopped and removed. Cards are no longer worked in the background on this computer.' };
+}
+/** npm arguments that install or update the service's own copy of the package. */
+export function updateArgs(dir, version = 'latest') {
+    return ['install', '--prefix', dir, '--no-audit', '--no-fund', '--loglevel=error', `${PACKAGE}@${version}`];
+}
+/**
+ * When this process is the service's own copy, the folder to update in place. Null for a copy started by
+ * npx, a global install or a source checkout: those update the way they were installed.
+ */
+export function managedRunnerDir(runningFile, amHome = agileMonsterHome()) {
+    const dir = runnerDir(amHome);
+    const resolved = path.resolve(runningFile);
+    return resolved.startsWith(path.resolve(dir) + path.sep) ? dir : null;
+}
+export async function describeService(deps = defaultServiceDeps()) {
+    const s = await serviceStatus(deps);
+    if (!s.supported)
+        return `Background runner: not available as a service on this system (${deps.platform}). ${KEEP_OPEN_HINT}`;
+    if (!s.installed)
+        return 'Background runner: not installed. Cards are worked only while your AI coding tool is open in the project folder.\nInstall it: npx -y @agilemonster/mcp-server service install';
+    const lines = [`Background runner: installed${s.running ? ' and running' : ', but not running right now'}.`];
+    lines.push(s.managed ? `  It starts with this computer and keeps itself up to date (${s.unitPath}).` : `  It was set up by hand and runs ${s.target || 'an unknown program'} (${s.unitPath}).`);
+    if (!s.running)
+        lines.push('  Start it again: npx -y @agilemonster/mcp-server service install' + (s.managed ? '' : ' --force'));
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilemonster/mcp-server",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "type": "module",
   "description": "Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)",
   "main": "dist/server.js",
@@ -47,6 +47,9 @@
   ],
   "author": "Agile Monster",
   "license": "MIT",
+  "engines": {
+    "node": ">=18.14"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1"
   },