@agilemonster/mcp-server 1.0.25 → 1.0.27

package/dist/server.js

@@ -8,13 +8,36 @@ 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';
-import { addPendingVerification, getCardState, loadMemory, recordAttempt, removePendingVerification, setCardState, setExplicitProfile, } from './deploy-memory.js';
+import { addPendingVerification, getBranchQuestion, getCardState, loadMemory, recordAttempt, removePendingVerification, setBranchQuestion, setCardState, setExplicitProfile, } from './deploy-memory.js';
+import { describeBlockedBranch, describePushConflict, parseBranchDirective, prepareBranch, shipOnlyCardCommits, startFromRemote, } from './branch-health.js';
 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) {
+    // A refused push has real ways out; "try again" on its own could never succeed
+    if (res.conflict)
+        return describePushConflict(res.conflict).options;
+    if (res.stage === 'git')
+        return [{ label: 'I fixed it, try again', reply: 'retry' }];
+    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 +286,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 +668,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 +1046,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 +1615,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)
@@ -1643,6 +1679,86 @@ function removeTaskLock(lockFile) {
     }
     catch { }
 }
+/**
+ * Look at the project's branch before any work is built on it.
+ *
+ *  'go'     the folder is fine (or was brought up to date, which is noted on the card)
+ *  'fresh'  the owner chose to start from the remote's version: unpushed commits are on a backup branch
+ *  'asked'  the branch cannot be pushed as it is, and the card now carries the question
+ *
+ * A check that cannot be made (no Git, no remote, offline) never holds a card up.
+ */
+async function ensureBranchReady(client, card, projectPath, provider, workerLabel, lockFile, replyAfter) {
+    let prep;
+    try {
+        prep = await prepareBranch(projectPath);
+    }
+    catch (err) {
+        log.warn('branch.check_failed', { card: card.id, project: projectPath, error: errorMessage(err) });
+        return 'go';
+    }
+    const pending = getBranchQuestion(projectPath, card.id);
+    if (prep.status !== 'blocked') {
+        if (pending)
+            setBranchQuestion(projectPath, card.id, null);
+        if (prep.status === 'updated') {
+            log.info('branch.updated', { card: card.id, project: projectPath, branch: prep.health.branch, behind: prep.health.behind, ahead: prep.health.ahead });
+            try {
+                await client.addProgress(card.id, provider, prep.note);
+            }
+            catch { }
+        }
+        return 'go';
+    }
+    const health = prep.health;
+    log.info('branch.blocked', { card: card.id, project: projectPath, branch: health.branch, behind: health.behind, ahead: health.ahead, files: health.conflictFiles.slice(0, 5) });
+    // Only a reply written after the question (or after the failed push that led here) is an answer to it
+    const since = [pending?.at, replyAfter].filter((t) => Boolean(t)).sort().pop() || null;
+    let reply = null;
+    if (since) {
+        try {
+            const human = latestHumanComment(await client.listComments(card.id));
+            reply = human && commentIsAfter(human, since) ? human : null;
+        }
+        catch (err) {
+            log.warn('card.comments_unavailable', { card: card.id, error: errorMessage(err) });
+        }
+    }
+    let prefix = '';
+    if (reply && parseBranchDirective(reply.text) === 'fresh') {
+        // Moving commits around in the project folder is for the person whose computer this is to decide
+        const ownerId = await machineOwnerId(client);
+        const authorId = reply.user_id ? String(reply.user_id) : '';
+        if (!ownerId || !authorId || authorId !== ownerId) {
+            prefix = 'Only the person whose computer runs this agent can decide what happens to the commits in its project folder. Please ask them to choose here.\n\n';
+        }
+        else {
+            const fresh = await startFromRemote(projectPath);
+            if (fresh.ok) {
+                setBranchQuestion(projectPath, card.id, null);
+                try {
+                    await client.addProgress(card.id, provider, `Done: the ${fresh.setAside === 1 ? 'unpushed commit is' : `${fresh.setAside} unpushed commits are`} safe on the branch \`${fresh.backup}\`, and the project folder now matches ${health.remoteLabel}. Files that only ${fresh.setAside === 1 ? 'that commit' : 'those commits'} added are on that branch too, and no longer in the folder. Starting on the card.`);
+                }
+                catch { }
+                return 'fresh';
+            }
+            prefix = `I could not do that: ${fresh.error}. Nothing was moved.\n\n`;
+        }
+    }
+    const { question, options } = describeBlockedBranch(health);
+    removeTaskLock(lockFile);
+    setBranchQuestion(projectPath, card.id, new Date().toISOString());
+    appendIdeActivityLog(projectPath, {
+        cardId: card.id,
+        cardTitle: card.title,
+        agentName: workerLabel,
+        model: card.agent_model || 'auto',
+        status: 'waiting_for_input',
+        summary: `Not started: \`${health.branch}\` is ${health.behind} behind and ${health.ahead} ahead of ${health.remoteLabel}, and the two clash.`,
+    });
+    await client.askQuestion(card.id, provider, prefix + question, options);
+    return 'asked';
+}
 /**
  * The code change for this card already exists — only its deployment failed. When the human replies
  * ("retry", or "deploy: <method or command>"), redo ONLY the deployment. Previously the whole card was
@@ -1665,7 +1781,8 @@ async function resumeFailedDeployment(client, card, projectPath, provider, worke
     if (reply && !parsed)
         return 'continue';
     const pendingRoute = state.pending_confirmation || null;
-    const choosesRoute = Boolean(parsed && (parsed.method || parsed.liveUrl || pendingRoute));
+    // (so does "ship only this change", which moves commits around in their project folder)
+    const choosesRoute = Boolean(parsed && (parsed.method || parsed.liveUrl || parsed.onlyThis || pendingRoute));
     if (choosesRoute) {
         // Choosing or confirming a route decides what is executed on THIS computer, so it has to come from the
         // person whose account this machine runs under — not from anyone who can comment on the board.
@@ -1683,7 +1800,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".
@@ -1703,15 +1820,33 @@ async function resumeFailedDeployment(client, card, projectPath, provider, worke
             set_by: 'the machine owner',
         });
     }
-    await client.addProgress(card.id, provider, directive.method
-        ? `Got it — deploying with **${methodLabel(directive.method)}**${directive.command ? ` (\`${directive.command}\`)` : ''}. I've saved this as the deployment route for this project, so future cards use it automatically.`
-        : 'Retrying the deployment of the change I already made (no code is being regenerated).');
+    // "Ship only this change": older unpushed commits go to a backup branch, this card's commit goes on top of the remote
+    let onlyThisNote = '';
+    if (directive.onlyThis) {
+        const only = await shipOnlyCardCommits(projectPath, card.id);
+        if (!only.ok) {
+            removeTaskLock(lockFile);
+            setCardState(projectPath, card.id, { ...state, at: new Date().toISOString() });
+            await client.askQuestion(card.id, provider, `I could not ship only this card's change: ${only.error}. Nothing was moved; the project folder is exactly as it was.\n\nIf you sort out the branch or push it yourself, reply **retry**: I will not redo the work, only push what is missing and check the deployment.`, [{ label: 'I fixed it, try again', reply: 'retry' }]);
+            return 'failed';
+        }
+        onlyThisNote =
+            `Putting only this card's change on top of the newer version and deploying it.` +
+                (only.setAside > 0 ? ` The ${only.setAside === 1 ? 'older commit is' : `${only.setAside} older commits are`} safe on the branch \`${only.backup}\` and ${only.setAside === 1 ? 'is' : 'are'} not deployed. Files that only ${only.setAside === 1 ? 'that commit' : 'those commits'} added are on that branch too, and no longer in the folder.` : '');
+    }
+    await client.addProgress(card.id, provider, onlyThisNote
+        ? onlyThisNote
+        : directive.method
+            ? `Got it — deploying with **${methodLabel(directive.method)}**${directive.command ? ` (\`${directive.command}\`)` : ''}. I've saved this as the deployment route for this project, so future cards use it automatically.`
+            : 'Retrying the deployment of the change I already made (no code is being regenerated).');
     const res = await runDeployment({
         projectPath,
         title: card.title || 'update',
         cardId: card.id,
         files: state.files,
-        redeploy: true,
+        // When the change never reached the remote, pushing it (or finding that a person already did) IS the retry:
+        // an empty "trigger redeploy" commit would deploy production a second time for nothing.
+        redeploy: state.failed_stage !== 'git',
         bound: boundProfileOf(card, await machineOwnerId(client)),
         override: directive.method ? { method: directive.method, command: directive.command } : null,
     });
@@ -1721,6 +1856,7 @@ async function resumeFailedDeployment(client, card, projectPath, provider, worke
             ...state,
             attempts: state.attempts + 1,
             last_error: res.errorDetail,
+            failed_stage: res.stage,
             at: new Date().toISOString(),
             pending_confirmation: res.errorKind === 'needs_confirmation' ? { method: res.method, command: res.command } : null,
         });
@@ -1734,9 +1870,9 @@ async function resumeFailedDeployment(client, card, projectPath, provider, worke
             summary: `Deployment retry failed: ${res.errorDetail.slice(0, 500)}`,
             files: state.files,
         });
-        await client.askQuestion(card.id, provider, res.errorKind === 'needs_confirmation'
+        await client.askQuestion(card.id, provider, res.errorKind === 'needs_confirmation' || res.stage === 'git'
             ? 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 +2040,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 +2052,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 +2111,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 +2123,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 +2169,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);
             }
         }
     }
@@ -2411,6 +2548,18 @@ export async function executeQueuedCardAutonomously(client, card, projectPath) {
         if (isRedeployOnlyCard(card)) {
             return await runRedeployOnlyCard(client, card, projectPath, provider, workerLabel, lockFile);
         }
+        // 1c. Can work be built and pushed from this folder? Look BEFORE the agent spends minutes on a branch that is
+        // behind its remote — and ask now, in plain words, if a person has to decide something first.
+        let earlierSummary = priorState?.summary || null;
+        const branchReady = await ensureBranchReady(client, card, projectPath, provider, workerLabel, lockFile, priorState?.at || null);
+        if (branchReady === 'asked')
+            return false;
+        if (branchReady === 'fresh') {
+            // The local commits (this card's earlier attempt included) are on a backup branch: start the card over
+            carryOverFiles = [];
+            earlierSummary = null;
+            setCardState(projectPath, card.id, null);
+        }
         const profile = resolveDeployProfile(projectPath, { bound: boundProfileOf(card, await machineOwnerId(client)), memory: loadMemory(projectPath) });
         const ownerId = await machineOwnerId(client);
         const run = {
@@ -2425,7 +2574,7 @@ export async function executeQueuedCardAutonomously(client, card, projectPath) {
             originalContents,
             ownerId,
             conversation: await cardConversation(client, card, ownerId),
-            earlierSummary: priorState?.summary || null,
+            earlierSummary,
             engineNotes: [],
             rollback,
         };
@@ -2489,6 +2638,7 @@ export async function executeQueuedCardAutonomously(client, card, projectPath) {
                 setCardState(projectPath, card.id, cardState('deploy_failed', {
                     commit: deployInfo.commitHash || null,
                     last_error: deployInfo.errorDetail,
+                    failed_stage: deployInfo.stage,
                     pending_confirmation: deployInfo.errorKind === 'needs_confirmation' ? { method: deployInfo.method, command: deployInfo.command } : null,
                 }));
                 removeTaskLock(lockFile);
@@ -2505,7 +2655,9 @@ 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)}`);
+                    : deployInfo.stage === 'git'
+                        ? `${describeFailureForHuman(deployInfo)}\n\nFiles I changed for this card: ${changed}.`
+                        : `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 +2972,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 +3039,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 +3118,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 +3149,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 +3176,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 +3187,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>;