@agilemonster/mcp-server 1.0.23 → 1.0.25

package/dist/agent-engine.js

@@ -0,0 +1,620 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agileMonsterHome, exec, execShell, readJson, which, writeJsonAtomic } from './runtime.js';
+/** The last complete JSON value an agent CLI printed (they print one result object, sometimes after other lines). */
+function lastJsonValue(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch { }
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line.startsWith('{') && !line.startsWith('['))
+            continue;
+        try {
+            return JSON.parse(line);
+        }
+        catch { }
+    }
+    return null;
+}
+function resultObject(stdout) {
+    const value = lastJsonValue(stdout);
+    if (Array.isArray(value)) {
+        for (let i = value.length - 1; i >= 0; i--) {
+            if (value[i] && typeof value[i] === 'object' && value[i].type === 'result')
+                return value[i];
+        }
+        return null;
+    }
+    return value && typeof value === 'object' ? value : null;
+}
+const ENGINES = [
+    {
+        id: 'claude',
+        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'];
+            if (opts.resumeSessionId)
+                args.push('--resume', opts.resumeSessionId);
+            if (opts.model && /^(claude|opus|sonnet|haiku|fable)/i.test(opts.model))
+                args.push('--model', opts.model);
+            // Shell access is what lets it run the build and the tests. The card's status belongs to the runner.
+            args.push('--allowedTools', 'Bash', '--disallowedTools', 'mcp__agilemonster');
+            return args;
+        },
+        parse: (res) => {
+            const obj = resultObject(res.stdout);
+            if (!obj)
+                return { text: res.stdout.trim() };
+            const text = typeof obj.result === 'string' ? obj.result : '';
+            return {
+                text,
+                sessionId: typeof obj.session_id === 'string' ? obj.session_id : undefined,
+                costUsd: typeof obj.total_cost_usd === 'number' ? obj.total_cost_usd : undefined,
+                error: obj.is_error ? text || String(obj.subtype || 'the run reported an error') : undefined,
+            };
+        },
+    },
+    {
+        id: 'cursor',
+        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())
+                return null;
+            const status = await exec(bin, ['status'], { timeoutMs: 20000 });
+            return /not logged in/i.test(`${status.stdout}\n${status.stderr}`)
+                ? 'it is installed but not signed in — run `cursor-agent login` once in a terminal'
+                : null;
+        },
+        args: (opts) => {
+            const args = ['-p', '--force', '--trust', '--output-format', 'json', '--workspace', opts.projectPath];
+            if (opts.resumeSessionId)
+                args.push('--resume', opts.resumeSessionId);
+            if (opts.model)
+                args.push('--model', opts.model);
+            args.push(opts.prompt);
+            return args;
+        },
+        parse: (res) => {
+            const obj = resultObject(res.stdout);
+            if (!obj)
+                return { text: res.stdout.trim() };
+            const text = typeof obj.result === 'string' ? obj.result : '';
+            return {
+                text,
+                sessionId: typeof obj.session_id === 'string' ? obj.session_id : undefined,
+                error: obj.is_error ? text || 'the run reported an error' : undefined,
+            };
+        },
+    },
+    {
+        id: 'codex',
+        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',
+        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 {
+                text = fs.readFileSync(scratch.lastMessageFile, 'utf8').trim();
+            }
+            catch { }
+            return { text: text || res.stdout.trim() };
+        },
+    },
+];
+const CUSTOM_ENGINE = { id: 'custom', label: 'your agent command', bin: '' };
+function customCommand() {
+    return (process.env.AGILEMONSTER_AGENT_COMMAND || '').trim();
+}
+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;
+    const cached = readyCache.get(bin);
+    if (cached && Date.now() - cached.at < READY_TTL_MS)
+        return cached.reason;
+    let reason = null;
+    try {
+        reason = await spec.ready(bin);
+    }
+    catch {
+        reason = null; // an unanswerable check must not hide a working agent: the run itself will tell
+    }
+    readyCache.set(bin, { at: Date.now(), reason });
+    return reason;
+}
+export function engineLabelFor(provider) {
+    const spec = ENGINES.find((e) => e.providers.includes((provider || '').toLowerCase()));
+    return spec ? spec.label : null;
+}
+/**
+ * The agent CLIs this machine can run for a card, best first: the card's own agent, then any other one that
+ * is installed. `AGILEMONSTER_AGENT_ENGINE` pins the choice (`claude`, `cursor`, `codex`) or switches the
+ * whole thing off (`builtin`); `AGILEMONSTER_AGENT_COMMAND` replaces it with a command of the developer's own.
+ *
+ * `notes` say, in words for the card, why a better engine was passed over — an installed CLI that is not
+ * signed in is one command away from working, and the developer should hear that.
+ */
+export async function resolveEngines(provider) {
+    const pinned = (process.env.AGILEMONSTER_AGENT_ENGINE || '').trim().toLowerCase();
+    if (['builtin', 'built-in', 'off', 'none', '0', 'false'].includes(pinned))
+        return { engines: [], notes: [] };
+    if (customCommand() && (!pinned || pinned === 'auto' || pinned === 'custom'))
+        return { engines: [CUSTOM_ENGINE], notes: [] };
+    const prov = (provider || '').toLowerCase();
+    const native = ENGINES.filter((e) => e.providers.includes(prov));
+    let ordered = [...native, ...ENGINES.filter((e) => !native.includes(e))];
+    if (pinned && pinned !== 'auto')
+        ordered = ENGINES.filter((e) => e.id === pinned);
+    const engines = [];
+    const notes = [];
+    for (const spec of ordered) {
+        const isNative = native.includes(spec);
+        const bin = findBin(spec);
+        if (!bin) {
+            if (isNative)
+                notes.push(`${spec.label}'s command line agent is not installed on this machine (\`${spec.installHint}\`)`);
+            continue;
+        }
+        const reason = await readiness(spec, bin);
+        if (reason) {
+            notes.push(`${spec.label}: ${reason}`);
+            continue;
+        }
+        engines.push({ id: spec.id, label: spec.label, bin });
+    }
+    return { engines, notes };
+}
+export function agentTimeoutMs() {
+    const minutes = Number(process.env.AGILEMONSTER_AGENT_TIMEOUT_MINUTES || '');
+    return (Number.isFinite(minutes) && minutes >= 1 ? Math.min(minutes, 180) : 30) * 60 * 1000;
+}
+function failureTail(res) {
+    return (res.stderr.trim() || res.stdout.trim() || res.tail).split('\n').filter((l) => l.trim()).slice(-4).join(' | ').slice(0, 500);
+}
+/** Run one agent to completion. Never throws: a CLI that is missing, logged out or crashed comes back as `ok: false`. */
+export async function runEngine(engine, opts) {
+    const started = Date.now();
+    const timeoutMs = opts.timeoutMs || agentTimeoutMs();
+    const scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'am-agent-'));
+    const scratch = { lastMessageFile: path.join(scratchDir, 'last-message.txt') };
+    // The agent works on the code. The card belongs to the runner, so its API key stays out of the agent's reach.
+    const env = { ...process.env };
+    delete env.AGILEMONSTER_API_KEY;
+    try {
+        if (engine.id === 'custom') {
+            const promptFile = path.join(scratchDir, 'prompt.md');
+            fs.writeFileSync(promptFile, opts.prompt, 'utf8');
+            const res = await execShell(customCommand(), {
+                cwd: opts.projectPath,
+                timeoutMs,
+                env: { ...env, AGILEMONSTER_PROMPT_FILE: promptFile, AGILEMONSTER_PROJECT_PATH: opts.projectPath },
+            });
+            const text = res.stdout.trim();
+            return {
+                ok: res.ok,
+                text,
+                timedOut: res.timedOut,
+                durationMs: Date.now() - started,
+                failure: res.ok ? undefined : res.timedOut ? `timed out after ${Math.round(timeoutMs / 60000)} minutes` : failureTail(res),
+            };
+        }
+        const spec = ENGINES.find((e) => e.id === engine.id);
+        if (!spec)
+            return { ok: false, text: '', timedOut: false, durationMs: 0, failure: `unknown engine ${engine.id}` };
+        let res = await exec(engine.bin, spec.args(opts, scratch), { cwd: opts.projectPath, timeoutMs, env });
+        // A model name the CLI does not know fails within seconds: the card's preference must not cost the whole run
+        if (!res.ok && !res.timedOut && opts.model && Date.now() - started < 45000 && /model/i.test(`${res.stderr}\n${res.stdout}`)) {
+            res = await exec(engine.bin, spec.args({ ...opts, model: null }, scratch), { cwd: opts.projectPath, timeoutMs, env });
+        }
+        const parsed = spec.parse(res, scratch);
+        const failed = !res.ok || !!parsed.error;
+        return {
+            ok: !failed,
+            text: parsed.text,
+            sessionId: parsed.sessionId,
+            costUsd: parsed.costUsd,
+            timedOut: res.timedOut,
+            durationMs: Date.now() - started,
+            failure: !failed ? undefined : res.timedOut ? `timed out after ${Math.round(timeoutMs / 60000)} minutes` : (parsed.error || failureTail(res)).slice(0, 500),
+        };
+    }
+    finally {
+        try {
+            fs.rmSync(scratchDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
+/**
+ * What the agent is told. It reads like a request typed into the IDE — the card, the thread, and the few
+ * rules that differ from an interactive session (nobody is there to answer, and the runner does the shipping).
+ */
+export function buildAgentPrompt(brief) {
+    const lines = [];
+    lines.push(`You are picking up a task card from the "${brief.boardName || 'project'}" board in Agile Monster. The repository is your current directory (${brief.projectPath}).`, 'Nobody is watching this session. Work the way you would for a developer who typed this request into the IDE and walked away: figure it out, build it, check it.', '', '## The card', `Title: ${brief.title.trim() || '(untitled)'}`, '', brief.description.trim() || '(no description — the title and the conversation below are the whole request)');
+    if (brief.conversation.length > 0) {
+        lines.push('', '## Conversation on the card (oldest first)');
+        for (const turn of brief.conversation) {
+            lines.push(`${turn.who === 'requester' ? 'Requester' : 'Agent (an earlier attempt)'}: ${turn.text.trim()}`, '');
+        }
+        lines.push('The requester\'s replies are part of the request. Where an earlier attempt asked a question, their reply is the answer — do not ask it again.');
+    }
+    lines.push('', '## How to work', '- Find the right place yourself. Search the code for the page names, labels and visible text the card mentions; never ask where something lives.', '- Where the card leaves a detail open, decide it the way this codebase already does things and say what you chose in your summary. Do not ask for confirmation of anything the requester already said.', '- Build the whole change, through every layer it needs (data/API, types, UI).', '- Check your work before you finish: run the type check, build or tests that cover what you touched, and fix what you broke.', '- Do not commit, push, deploy, stash or switch branches. When you finish, the Agile Monster runner commits and deploys exactly the files you changed.', '- Do not use Agile Monster MCP tools or its API. This card is already claimed and its status is managed for you, so skip any project instruction about claiming cards or submitting them for review.');
+    if (brief.developerFiles.length > 0) {
+        lines.push(`- These files hold the developer's own uncommitted work. Do not modify them: ${brief.developerFiles.slice(0, 40).map((f) => `\`${f}\``).join(', ')}`);
+    }
+    if (brief.earlierFiles.length > 0) {
+        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"}');
+    return lines.join('\n');
+}
+/** Read the closing JSON object out of the agent's final message. Tolerates code fences and prose around it. */
+export function parseAgentReport(text) {
+    const clean = (text || '').trim();
+    const starts = [];
+    const re = /\{\s*"status"\s*:/g;
+    let m;
+    while ((m = re.exec(clean)))
+        starts.push(m.index);
+    for (let i = starts.length - 1; i >= 0; i--) {
+        let end = clean.lastIndexOf('}');
+        while (end > starts[i]) {
+            try {
+                const obj = JSON.parse(clean.slice(starts[i], end + 1));
+                const status = String(obj.status || '').toLowerCase();
+                const steps = Array.isArray(obj.verification_steps)
+                    ? obj.verification_steps.map((s) => String(s).trim()).filter(Boolean)
+                    : typeof obj.verification_steps === 'string' && obj.verification_steps.trim()
+                        ? [obj.verification_steps.trim()]
+                        : [];
+                return {
+                    status: status === 'done' ? 'done' : status === 'blocked' ? 'blocked' : 'unknown',
+                    summary: String(obj.summary || '').trim(),
+                    verificationSteps: steps,
+                    question: String(obj.question || '').trim(),
+                };
+            }
+            catch { }
+            end = clean.lastIndexOf('}', end - 1);
+        }
+    }
+    return { status: 'unknown', summary: '', verificationSteps: [], question: '' };
+}
+/** 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) {
+    const clean = (text || '').replace(/```(?:json)?\s*\{\s*"status"[\s\S]*?```/g, '').replace(/\{\s*"status"\s*:[\s\S]*$/, '').trim();
+    return clean.length > maxChars ? `…${clean.slice(-maxChars)}` : clean;
+}
+const ABSENT = 'absent';
+const MAX_FINGERPRINT_BYTES = 8 * 1024 * 1024;
+const MAX_SAVED_BYTES = 2 * 1024 * 1024;
+const git = (cwd, args, timeoutMs = 30000) => exec('git', ['--literal-pathspecs', ...args], { cwd, timeoutMs });
+function fingerprint(abs) {
+    try {
+        const stat = fs.statSync(abs);
+        if (!stat.isFile())
+            return `other:${stat.mtimeMs}`;
+        if (stat.size > MAX_FINGERPRINT_BYTES)
+            return `big:${stat.size}:${stat.mtimeMs}`;
+        return crypto.createHash('sha1').update(fs.readFileSync(abs)).digest('hex');
+    }
+    catch {
+        return ABSENT;
+    }
+}
+/** Paths from `git status --porcelain -z`. A rename reports both its new and its old path. */
+export function parsePorcelainZ(out) {
+    const paths = [];
+    const tokens = out.split('\0');
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.length < 4)
+            continue;
+        paths.push(token.slice(3));
+        if (token[0] === 'R' || token[0] === 'C') {
+            i++;
+            if (tokens[i])
+                paths.push(tokens[i]);
+        }
+    }
+    return paths;
+}
+async function statusPaths(projectPath) {
+    const res = await git(projectPath, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+    return res.ok ? parsePorcelainZ(res.stdout) : null;
+}
+/** Record the working tree before the agent starts. Null when the folder is not a Git repository. */
+export async function snapshotWorkingTree(projectPath) {
+    const head = await git(projectPath, ['rev-parse', 'HEAD']);
+    const paths = await statusPaths(projectPath);
+    if (!head.ok || !paths)
+        return null;
+    const entries = new Map();
+    const saved = new Map();
+    for (const rel of paths) {
+        const abs = path.join(projectPath, rel);
+        const print = fingerprint(abs);
+        entries.set(rel, print);
+        if (print === ABSENT) {
+            saved.set(rel, null);
+        }
+        else {
+            try {
+                if (fs.statSync(abs).size <= MAX_SAVED_BYTES)
+                    saved.set(rel, fs.readFileSync(abs));
+            }
+            catch { }
+        }
+    }
+    return { head: head.stdout.trim(), entries, saved };
+}
+/** Files an agent's own tooling drops into a project. New ones are never part of a card's change. */
+function isAgentToolingPath(rel) {
+    return /^(\.claude|\.cursor|\.codex|\.agilemonster|\.specstory)(\/|$)/.test(rel) || rel === '.agilemonster.json';
+}
+/**
+ * Compare the working tree with the snapshot. If the agent committed despite its instructions, the commits
+ * are undone first (soft, so nothing is lost) — unless they were pushed, which only a human can sort out.
+ */
+export async function changesSince(projectPath, snap) {
+    let pushedCommit;
+    const head = await git(projectPath, ['rev-parse', 'HEAD']);
+    const nowHead = head.ok ? head.stdout.trim() : snap.head;
+    if (nowHead !== snap.head) {
+        const descends = await git(projectPath, ['merge-base', '--is-ancestor', snap.head, nowHead]);
+        const onRemote = await git(projectPath, ['branch', '-r', '--contains', nowHead]);
+        if (onRemote.ok && onRemote.stdout.trim() !== '') {
+            pushedCommit = nowHead;
+        }
+        else if (descends.ok) {
+            await git(projectPath, ['reset', '--soft', snap.head]);
+        }
+    }
+    const changed = [];
+    const overlapping = [];
+    const now = new Set((await statusPaths(projectPath)) || []);
+    for (const rel of now) {
+        const before = snap.entries.get(rel);
+        if (before === undefined) {
+            if (!isAgentToolingPath(rel))
+                changed.push(rel);
+        }
+        else if (fingerprint(path.join(projectPath, rel)) !== before) {
+            changed.push(rel);
+            overlapping.push(rel);
+        }
+    }
+    // A file that was dirty and is clean again was put back to HEAD by the agent: the developer's change is gone
+    for (const rel of snap.entries.keys()) {
+        if (!now.has(rel)) {
+            changed.push(rel);
+            overlapping.push(rel);
+        }
+    }
+    return { changed: changed.sort(), overlapping: overlapping.sort(), pushedCommit };
+}
+/**
+ * Put the given files back the way the snapshot found them. Returns the files that could not be restored
+ * (only possible for a file the developer had changed that was too large to keep a copy of).
+ */
+export async function restoreWorkingTree(projectPath, snap, paths) {
+    const failed = [];
+    const root = path.resolve(projectPath);
+    for (const rel of paths) {
+        const abs = path.resolve(root, rel);
+        if (abs !== root && !abs.startsWith(root + path.sep))
+            continue;
+        try {
+            if (snap.entries.has(rel)) {
+                if (!snap.saved.has(rel)) {
+                    failed.push(rel);
+                    continue;
+                }
+                const original = snap.saved.get(rel);
+                if (original === null || original === undefined) {
+                    fs.rmSync(abs, { force: true });
+                }
+                else {
+                    fs.mkdirSync(path.dirname(abs), { recursive: true });
+                    fs.writeFileSync(abs, original);
+                }
+                continue;
+            }
+            // Clean before the run: either a tracked file (take it from HEAD) or one that did not exist (remove it)
+            const tracked = await git(projectPath, ['cat-file', '-e', `${snap.head}:${rel}`]);
+            if (tracked.ok) {
+                const back = await git(projectPath, ['checkout', snap.head, '--', rel]);
+                if (!back.ok)
+                    failed.push(rel);
+            }
+            else {
+                await git(projectPath, ['rm', '--cached', '--quiet', '--ignore-unmatch', '--', rel]);
+                fs.rmSync(abs, { force: true });
+                let dir = path.dirname(abs);
+                while (dir !== root && dir.startsWith(root + path.sep)) {
+                    try {
+                        fs.rmdirSync(dir); // only succeeds on a directory the agent created and we just emptied
+                    }
+                    catch {
+                        break;
+                    }
+                    dir = path.dirname(dir);
+                }
+            }
+        }
+        catch {
+            failed.push(rel);
+        }
+    }
+    return failed;
+}
+/**
+ * `git diff` does not show files Git has never seen. Mark the agent's new files as "to be added" (no content
+ * is staged) so the reviewer's diff includes them.
+ */
+export async function markNewFilesForDiff(projectPath, files) {
+    if (files.length === 0)
+        return;
+    const untracked = await git(projectPath, ['ls-files', '--others', '--exclude-standard', '-z', '--', ...files]);
+    const fresh = untracked.ok ? untracked.stdout.split('\0').filter(Boolean) : [];
+    if (fresh.length > 0)
+        await git(projectPath, ['add', '--intent-to-add', '--', ...fresh]);
+}
+function runRecordFile(cardId) {
+    return path.join(agileMonsterHome(), 'agent-runs', `${cardId.replace(/[^a-zA-Z0-9-]/g, '')}.json`);
+}
+/**
+ * Snapshot the tree before this card's agent starts, and note that a run is in progress.
+ *
+ * `interrupted` is true when an earlier run of the same card never reached a conclusion (the machine slept,
+ * the daemon was killed). Whatever that run left in the tree cannot be told apart from the developer's own
+ * edits, so it is treated as theirs — never reverted, never committed — and the card can say where the
+ * leftovers probably came from.
+ */
+export async function baselineFor(cardId, projectPath) {
+    const snapshot = await snapshotWorkingTree(projectPath);
+    if (!snapshot)
+        return null;
+    const prior = readJson(runRecordFile(cardId));
+    const interrupted = !!prior && prior.project_path === projectPath;
+    try {
+        writeJsonAtomic(runRecordFile(cardId), {
+            card_id: cardId,
+            project_path: projectPath,
+            pid: process.pid,
+            at: new Date().toISOString(),
+        });
+    }
+    catch { }
+    return { snapshot, interrupted };
+}
+/** The card's run reached a conclusion (shipped, reverted, or handed to the human): it is no longer in progress. */
+export function clearBaseline(cardId) {
+    try {
+        fs.rmSync(runRecordFile(cardId), { force: true });
+    }
+    catch { }
+}

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { ActiveClaim, AgileMonsterProjectConfig, AutonomousStepResponse, CardComment, DeployReport, Board, BoardAgentConfig, Card, ContextResponse, DiscoveredProject, PulseResponse } from './types.js';
-export declare const MCP_SERVER_VERSION = "1.0.23";
+export declare const MCP_SERVER_VERSION = "1.0.25";
 /** 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;

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.23';
+export const MCP_SERVER_VERSION = '1.0.25';
 /** An API call the server answered with an error status. `status` lets callers tell "refused" from "broken". */
 export class ApiError extends Error {
     status;

package/dist/server.d.ts

@@ -36,7 +36,7 @@ export declare function createServer(client?: AgileMonsterClient): Server<{
         } | undefined;
     } | undefined;
 }>;
-export declare function collectProjectSourceFiles(projectPath: string, keywords: string[]): string[];
+export declare function collectProjectSourceFiles(projectPath: string, keywords: string[], phrases?: string[]): string[];
 /**
  * The board binding's deploy profile for a card, as this machine may use it. A route that another account
  * set arrives as a proposal (or is demoted to one here): see trustBoundRoute and resolveDeployProfile.
@@ -64,6 +64,10 @@ export declare function recoverEditJournals(): number;
  * Anchored to the start of the title so "Add a restart button to the server page" is not one.
  */
 export declare function isRedeployOnlyCard(card: Pick<Card, 'title'>): boolean;
+/** The part of a build log that names the problem, without colour codes. Falls back to the last lines. */
+export declare function buildErrorExcerpt(output: string, maxLines?: number, maxChars?: number): string;
+/** Exact phrases the requester put in quotes ("Recently active projects"): the strongest pointer to the right file. */
+export declare function quotedPhrases(text: string): string[];
 export declare function executeQueuedCardAutonomously(client: AgileMonsterClient, card: Card, projectPath: string): Promise<boolean>;
 /**
  * Finish a card the human approved into Done (or flagged as `deploying`).