@agilemonster/mcp-server 1.0.24 → 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,18 +100,50 @@ 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` once to sign in |
+| 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` |
 
-If the card's own agent has no CLI here, any other installed one is used and the card says which. The agent
-gets the card, the requester's replies on it, and three rules: decide open details the way the codebase
+The runner also finds an agent that is not on your `PATH` — for example the Codex CLI that the Codex app and
+its IDE plugin install, already signed in with your ChatGPT account — so there is often nothing to set up.
+If the card's own agent cannot run here, any other ready one stands in and the card says which, and why.
+
+To see what this machine will use, and the one step that would fix an agent that is not ready:
+
+```bash
+npx @agilemonster/mcp-server agents
+```
+
+The agent gets the card, the requester's replies on it, and three rules: decide open details the way the codebase
 already does instead of asking, check your own work, and do not commit — the runner commits and deploys
 exactly the files the agent changed, after its own build check.
 
@@ -144,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',
@@ -23,6 +23,38 @@ const firstArg = process.argv[2];
 if (firstArg === '--version' || firstArg === '-v' || firstArg === 'version') {
   console.log(MCP_SERVER_VERSION);
   process.exit(0);
+} else if (firstArg === 'agents' || firstArg === 'doctor') {
+  // Which coding agent on this machine works a card queued from the board, and what would fix the others
+  const { describeAgents, forgetEngineReadiness } = await import('../dist/agent-engine.js');
+  const { ensureUserPath } = await import('../dist/runtime.js');
+  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

@@ -35,6 +35,21 @@ export interface ResolvedEngine {
     label: string;
     bin: string;
 }
+/** Forget cached sign-in checks (a developer who just signed in should not wait out the cache; tests). */
+export declare function forgetEngineReadiness(): void;
+export interface EngineStatus {
+    id: EngineId;
+    label: string;
+    bin: string | null;
+    /** Null when this agent can take a card now, otherwise what stands in the way, in words for the developer. */
+    problem: string | null;
+}
+/** Every agent CLI this runner knows, and whether each can take a card on this machine right now. */
+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
@@ -77,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

@@ -41,7 +41,18 @@ const ENGINES = [
         label: 'Claude Code',
         providers: ['claude_code'],
         bins: ['claude'],
+        locations: () => [path.join(os.homedir(), '.local', 'bin', 'claude'), path.join(os.homedir(), '.claude', 'local', 'claude')],
         installHint: 'npm install -g @anthropic-ai/claude-code',
+        ready: async (bin) => {
+            if ((process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN || '').trim())
+                return null;
+            const status = await exec(bin, ['auth', 'status'], { timeoutMs: 20000 });
+            const info = lastJsonValue(status.stdout);
+            // Only a plain "not signed in to Anthropic" is certain. Bedrock, Vertex and older CLIs answer differently: let the run tell.
+            return info && typeof info === 'object' && info.loggedIn === false && (!info.apiProvider || info.apiProvider === 'firstParty')
+                ? 'it is installed but not signed in — run `claude auth login` once in a terminal'
+                : null;
+        },
         args: (opts) => {
             // The prompt directly follows -p; the list-valued flags come last so they cannot swallow it.
             const args = ['-p', opts.prompt, '--output-format', 'json', '--permission-mode', 'acceptEdits'];
@@ -71,6 +82,7 @@ const ENGINES = [
         label: 'Cursor Agent',
         providers: ['cursor'],
         bins: ['cursor-agent'],
+        locations: () => [path.join(os.homedir(), '.local', 'bin', 'cursor-agent')],
         installHint: 'curl https://cursor.com/install -fsS | bash',
         ready: async (bin) => {
             if ((process.env.CURSOR_API_KEY || '').trim())
@@ -106,8 +118,28 @@ const ENGINES = [
         label: 'Codex',
         providers: ['codex'],
         bins: ['codex'],
+        // The Codex app and its IDE plugin ship the same CLI, already signed in with the developer's ChatGPT account
+        locations: () => [
+            path.join(os.homedir(), '.codex', 'plugins', '.plugin-appserver', 'codex-cli', 'bin', 'codex'),
+            '/Applications/Codex.app/Contents/Resources/codex',
+        ],
         installHint: 'npm install -g @openai/codex',
-        args: (opts, scratch) => ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-o', scratch.lastMessageFile, opts.prompt],
+        ready: async (bin) => {
+            if ((process.env.CODEX_API_KEY || '').trim())
+                return null;
+            const status = await exec(bin, ['login', 'status'], { timeoutMs: 20000 });
+            return /not logged in/i.test(`${status.stdout}\n${status.stderr}`)
+                ? 'it is installed but not signed in — run `codex login` once in a terminal'
+                : null;
+        },
+        args: (opts, scratch) => {
+            // workspace-write keeps its edits inside the project; network stays on so it can install and build like the IDE does
+            const args = ['exec', '--sandbox', 'workspace-write', '-c', 'sandbox_workspace_write.network_access=true', '--skip-git-repo-check'];
+            if (opts.model && /^gpt-/i.test(opts.model))
+                args.push('-m', opts.model);
+            args.push('-o', scratch.lastMessageFile, opts.prompt);
+            return args;
+        },
         parse: (res, scratch) => {
             let text = '';
             try {
@@ -124,6 +156,77 @@ function customCommand() {
 }
 const READY_TTL_MS = 2 * 60 * 1000;
 const readyCache = new Map();
+/** Forget cached sign-in checks (a developer who just signed in should not wait out the cache; tests). */
+export function forgetEngineReadiness() {
+    readyCache.clear();
+}
+function isExecutableFile(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The engine's CLI: on PATH, or where its installer, IDE plugin or desktop app keeps it. */
+function findBin(spec) {
+    for (const bin of spec.bins) {
+        const onPath = which(bin);
+        if (onPath)
+            return onPath;
+    }
+    for (const candidate of spec.locations ? spec.locations() : []) {
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Every agent CLI this runner knows, and whether each can take a card on this machine right now. */
+export async function engineStatuses() {
+    const out = [];
+    for (const spec of ENGINES) {
+        const bin = findBin(spec);
+        out.push({
+            id: spec.id,
+            label: spec.label,
+            bin,
+            problem: bin ? await readiness(spec, bin) : `it is not installed (\`${spec.installHint}\`)`,
+        });
+    }
+    return out;
+}
+/** What `agilemonster agents` prints: which agent works a queued card here, and the one step that would fix the others. */
+export async function describeAgents() {
+    const pinned = (process.env.AGILEMONSTER_AGENT_ENGINE || '').trim().toLowerCase();
+    const lines = ['Coding agents on this machine that can work a card queued from the board:', ''];
+    if (customCommand())
+        lines.push(`  ✓ Your own command   AGILEMONSTER_AGENT_COMMAND=${customCommand()}`, '');
+    const statuses = await engineStatuses();
+    for (const s of statuses) {
+        lines.push(`  ${s.problem ? '✗' : '✓'} ${s.label.padEnd(14)} ${s.problem ? s.problem : s.bin}`);
+    }
+    lines.push('');
+    const usable = statuses.filter((s) => !s.problem);
+    if (['builtin', 'built-in', 'off', 'none', '0', 'false'].includes(pinned)) {
+        lines.push('AGILEMONSTER_AGENT_ENGINE switches agents off: every card runs on the built-in engine (a few files, one pass).');
+    }
+    else if (customCommand()) {
+        lines.push('Every card you created is handed to your own command.');
+    }
+    else if (usable.length === 0) {
+        lines.push('None is ready, so cards run on the built-in engine, which edits a few files in one pass and cannot explore or build.');
+        lines.push('Fix any one line above and the next card is worked by a real agent.');
+    }
+    else {
+        for (const s of statuses) {
+            const worker = s.problem ? usable[0] : s;
+            lines.push(`A card assigned to ${s.label.replace(/ Agent$/, '')} is worked by ${worker.label}${s.problem ? ` (standing in)` : ''}.`);
+        }
+        lines.push('Cards a teammate created always use the built-in engine: an agent with a shell only works cards you wrote.');
+    }
+    return lines.join('\n');
+}
 async function readiness(spec, bin) {
     if (!spec.ready)
         return null;
@@ -140,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;
@@ -167,7 +279,7 @@ export async function resolveEngines(provider) {
     const notes = [];
     for (const spec of ordered) {
         const isNative = native.includes(spec);
-        const bin = spec.bins.map((b) => which(b)).find(Boolean) || null;
+        const bin = findBin(spec);
         if (!bin) {
             if (isNative)
                 notes.push(`${spec.label}'s command line agent is not installed on this machine (\`${spec.installHint}\`)`);
@@ -265,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. */
@@ -292,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.24";
+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.24';
+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?: {