@agilemonster/mcp-server 1.0.26 → 1.0.27

package/README.md

@@ -178,13 +178,17 @@ What the runner guarantees:
 - **Verifies before claiming "Deployed"** — deploy workflow run for that commit, container state and health, script exit code, and a smoke check of a URL you provided. A guessed URL can never fail a deploy.
 - **Asks once, then remembers** — an unconfirmed deploy script, cloud CLI or manually-dispatched workflow is not run on a guess. Reply on the card with `deploy: <command or method>` to confirm; `retry` re-runs only the deployment, not the code change.
 - **Heals what it can** — starts Docker Desktop/OrbStack if it is installed but stopped, rebases and re-pushes when the remote moved ahead, retries network errors, and falls back to the next route when the chosen one plainly does not apply.
+- **Checks the branch before it starts** — fetches, and fast-forwards a folder that is only behind (Git refuses if that would touch an uncommitted edit of yours). Unpushed commits that fit are replayed on top. If unpushed commits clash with the remote, the card asks first, in plain words, instead of letting an agent work for minutes on something that cannot be pushed.
+- **A refused push comes with ways out** — the card says what clashes (this card, or older commits that never left this computer) and offers **Ship only this change** or **Redo on the latest version**. Anything moved out of the way is kept on an `agilemonster/backup-…` branch; nothing is deleted. If you push the change yourself, `retry` only checks the deployment: no second commit, no second deploy.
 - **Never reports a slow pipeline as failed** — a CI run that outlives the wait is marked pending and re-checked on later pulses; the outcome is posted on the card.
 
 State lives outside your repositories: `~/.agilemonster/projects/` (per-project deployment history) and
 `~/.agilemonster/logs/daemon.jsonl` (structured daemon log).
 
 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`
+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` · `deploy: only this change` · `branch: start fresh`
+
+Replies that decide what runs or what moves on your computer (`deploy: …`, `branch: start fresh`) are only taken from the person whose account the runner uses.
 
 ---
 

package/dist/branch-health.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Is the project folder in a state where work can be built and pushed?
+ *
+ * A card used to fail only at the very end: the agent worked for minutes on a branch that was behind its remote,
+ * and the push then stopped on a conflict that had nothing to do with the card. This module looks BEFORE the
+ * agent starts, brings the folder up to date when that is safe, and otherwise says in plain words what is in
+ * the way and what the owner can choose.
+ *
+ * Nothing here ever discards work: commits that are moved out of the way stay on a backup branch.
+ */
+export interface UnpushedCommit {
+    sha: string;
+    subject: string;
+    /** YYYY-MM-DD */
+    date: string;
+}
+export interface BranchHealth {
+    isRepo: boolean;
+    /** Empty when HEAD is detached. */
+    branch: string;
+    remote: string;
+    /** e.g. `origin/main`. Empty when this branch does not exist on the remote (or there is no remote). */
+    upstream: string;
+    /** Where the remote lives, in words for a card: "GitHub", "GitLab", "Bitbucket" or "the remote". */
+    remoteLabel: string;
+    /** The remote answered just now, so `ahead` / `behind` are current. */
+    fetched: boolean;
+    ahead: number;
+    behind: number;
+    /** Tracked files with uncommitted changes. (Untracked files are no obstacle to updating.) */
+    dirty: boolean;
+    /** Commits on this computer that were never pushed, newest first. */
+    unpushed: UnpushedCommit[];
+    /** Only when both sides moved: do the unpushed commits fit on top of the remote? null = could not tell. */
+    fitsOnRemote: boolean | null;
+    conflictFiles: string[];
+}
+export declare function remoteLabelFor(url: string): string;
+export declare function inspectBranch(cwd: string, options?: {
+    fetch?: boolean;
+}): Promise<BranchHealth>;
+export type BranchPreparation = {
+    status: 'ready';
+    health: BranchHealth;
+} | {
+    status: 'updated';
+    health: BranchHealth;
+    note: string;
+} | {
+    status: 'blocked';
+    health: BranchHealth;
+};
+/**
+ * Bring the folder up to date with its remote when that cannot hurt anything:
+ *  - only behind: fast-forward (Git itself refuses if that would touch an uncommitted edit);
+ *  - both sides moved and the unpushed commits fit: replay them on top, but only in a clean tree;
+ *  - both sides moved and they clash: 'blocked' — a person has to choose, before any work is built on it.
+ * When the remote cannot be reached, nothing is decided on stale information.
+ */
+export declare function prepareBranch(cwd: string): Promise<BranchPreparation>;
+/** The reply that picks "start from the remote's version". */
+export declare function parseBranchDirective(text: string): 'fresh' | null;
+export declare const START_FRESH_REPLY = "branch: start fresh";
+/** The question on the card when the folder is blocked before any work started. */
+export declare function describeBlockedBranch(health: BranchHealth): {
+    question: string;
+    options: Array<{
+        label: string;
+        reply: string;
+    }>;
+};
+export interface SetAsideResult {
+    ok: boolean;
+    backup: string;
+    setAside: number;
+    error?: string;
+}
+/**
+ * "Start from the remote's version": keep every unpushed commit on a backup branch, then make the local branch
+ * equal to the remote. Refuses when there are uncommitted changes, which a reset would destroy.
+ */
+export declare function startFromRemote(cwd: string): Promise<SetAsideResult>;
+export interface PushConflict {
+    branch: string;
+    remoteLabel: string;
+    behind: number;
+    /** Unpushed commits that are NOT this card's (older work that never left this computer). */
+    older: UnpushedCommit[];
+    /** This card's commits, oldest first. */
+    cardCommits: string[];
+    conflictFiles: string[];
+    /** Does this card's change fit on the remote's version without the older commits? null = could not tell. */
+    cardFitsAlone: boolean | null;
+}
+export declare const cardTag: (cardId: string) => string;
+/** Work out, after a refused push, what actually clashes — the card, or older commits that were never pushed. */
+export declare function explainPushConflict(cwd: string, cardId: string, unmergedFiles?: string[]): Promise<PushConflict | null>;
+export declare const ONLY_THIS_REPLY = "deploy: only this change";
+/** Plain words for the card, the way out, and the buttons that take it. */
+export declare function describePushConflict(c: PushConflict): {
+    detail: string;
+    hint: string;
+    options: Array<{
+        label: string;
+        reply: string;
+    }>;
+};
+export interface ShipOnlyResult {
+    ok: boolean;
+    backup: string;
+    setAside: number;
+    error?: string;
+}
+/**
+ * "Ship only this change": keep the whole local branch on a backup branch, make the branch equal to the remote,
+ * and put only this card's commits back on top. If they do not apply, everything is put back as it was.
+ */
+export declare function shipOnlyCardCommits(cwd: string, cardId: string): Promise<ShipOnlyResult>;

package/dist/branch-health.js

@@ -0,0 +1,302 @@
+import { exec, log } from './runtime.js';
+const GIT_ENV = () => ({ ...process.env, GIT_TERMINAL_PROMPT: '0' });
+const run = (cwd, args, timeoutMs = 45000) => exec('git', args, { cwd, timeoutMs, env: GIT_ENV() });
+export function remoteLabelFor(url) {
+    if (/github\.com/i.test(url))
+        return 'GitHub';
+    if (/gitlab/i.test(url))
+        return 'GitLab';
+    if (/bitbucket/i.test(url))
+        return 'Bitbucket';
+    return 'the remote';
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const fileList = (files) => {
+    const shown = files.slice(0, 3).map((f) => `\`${f}\``);
+    const more = files.length - shown.length;
+    return shown.join(', ') + (more > 0 ? ` and ${plural(more, 'other file')}` : '');
+};
+async function unpushedCommits(cwd, upstream) {
+    const out = await run(cwd, ['log', '--max-count=30', '--format=%h%x09%cs%x09%s', `${upstream}..HEAD`]);
+    if (!out.ok)
+        return [];
+    return out.stdout
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => {
+        const [sha, date, ...subject] = line.split('\t');
+        return { sha, date: date || '', subject: subject.join('\t') };
+    });
+}
+/**
+ * Would merging `theirs` into `ours` conflict? Asked of Git without touching the working tree
+ * (`git merge-tree --write-tree`, Git 2.38+). `base` replays a single range the way a cherry-pick would.
+ */
+async function mergeFits(cwd, ours, theirs, base) {
+    const args = ['merge-tree', '--write-tree', '--name-only', '--no-messages'];
+    if (base)
+        args.push(`--merge-base=${base}`);
+    const out = await run(cwd, [...args, ours, theirs]);
+    if (out.code === 0)
+        return { fits: true, files: [] };
+    if (out.code === 1) {
+        // First line is the resulting tree; the conflicted paths follow
+        const files = out.stdout.split(/\r?\n/).slice(1).map((l) => l.trim()).filter(Boolean);
+        return { fits: false, files: Array.from(new Set(files)) };
+    }
+    return { fits: null, files: [] }; // an older Git: we simply do not know
+}
+export async function inspectBranch(cwd, options = {}) {
+    const health = {
+        isRepo: false,
+        branch: '',
+        remote: '',
+        upstream: '',
+        remoteLabel: 'the remote',
+        fetched: false,
+        ahead: 0,
+        behind: 0,
+        dirty: false,
+        unpushed: [],
+        fitsOnRemote: null,
+        conflictFiles: [],
+    };
+    health.isRepo = (await run(cwd, ['rev-parse', '--is-inside-work-tree'])).stdout.trim() === 'true';
+    if (!health.isRepo)
+        return health;
+    health.branch = (await run(cwd, ['branch', '--show-current'])).stdout.trim();
+    health.dirty = (await run(cwd, ['status', '--porcelain', '--untracked-files=no'])).stdout.trim().length > 0;
+    if (!health.branch)
+        return health;
+    const remotes = (await run(cwd, ['remote'])).stdout.split(/\s+/).filter(Boolean);
+    if (remotes.length === 0)
+        return health;
+    const configured = (await run(cwd, ['config', '--get', `branch.${health.branch}.remote`])).stdout.trim();
+    health.remote = configured && remotes.includes(configured) ? configured : remotes.includes('origin') ? 'origin' : remotes[0];
+    health.remoteLabel = remoteLabelFor((await run(cwd, ['remote', 'get-url', health.remote])).stdout.trim());
+    if (options.fetch !== false) {
+        health.fetched = (await run(cwd, ['fetch', health.remote, health.branch], 60000)).ok;
+    }
+    const ref = `${health.remote}/${health.branch}`;
+    if (!(await run(cwd, ['rev-parse', '--verify', '--quiet', `refs/remotes/${ref}`])).ok)
+        return health;
+    health.upstream = ref;
+    const counts = (await run(cwd, ['rev-list', '--left-right', '--count', `HEAD...${ref}`])).stdout.trim().split(/\s+/);
+    health.ahead = Number(counts[0]) || 0;
+    health.behind = Number(counts[1]) || 0;
+    if (health.ahead > 0)
+        health.unpushed = await unpushedCommits(cwd, ref);
+    if (health.ahead > 0 && health.behind > 0) {
+        const merge = await mergeFits(cwd, ref, 'HEAD');
+        health.fitsOnRemote = merge.fits;
+        health.conflictFiles = merge.files;
+    }
+    return health;
+}
+/**
+ * Bring the folder up to date with its remote when that cannot hurt anything:
+ *  - only behind: fast-forward (Git itself refuses if that would touch an uncommitted edit);
+ *  - both sides moved and the unpushed commits fit: replay them on top, but only in a clean tree;
+ *  - both sides moved and they clash: 'blocked' — a person has to choose, before any work is built on it.
+ * When the remote cannot be reached, nothing is decided on stale information.
+ */
+export async function prepareBranch(cwd) {
+    const health = await inspectBranch(cwd);
+    if (!health.isRepo || !health.branch || !health.upstream || !health.fetched || health.behind === 0) {
+        return { status: 'ready', health };
+    }
+    const newer = plural(health.behind, 'newer commit');
+    if (health.ahead === 0) {
+        const ff = await run(cwd, ['merge', '--ff-only', health.upstream], 120000);
+        if (ff.ok) {
+            return { status: 'updated', health, note: `Before starting, I brought this project folder up to date with ${health.remoteLabel} (${newer} on \`${health.branch}\`).` };
+        }
+        // An uncommitted edit of the developer's is in the way of the update: leave their folder exactly as it is
+        log.info('branch.fast_forward_skipped', { project: cwd, branch: health.branch, behind: health.behind, reason: ff.tail.slice(0, 200) });
+        return { status: 'ready', health };
+    }
+    if (health.fitsOnRemote === false)
+        return { status: 'blocked', health };
+    if (health.fitsOnRemote === null || health.dirty)
+        return { status: 'ready', health };
+    const rebase = await run(cwd, ['rebase', health.upstream], 120000);
+    if (rebase.ok) {
+        return {
+            status: 'updated',
+            health,
+            note: `Before starting, I brought this project folder up to date with ${health.remoteLabel} (${newer} on \`${health.branch}\`); the ${plural(health.ahead, 'commit')} that had not been pushed from this computer now sit on top.`,
+        };
+    }
+    const unmerged = (await run(cwd, ['diff', '--name-only', '--diff-filter=U'])).stdout.split(/\r?\n/).filter(Boolean);
+    await run(cwd, ['rebase', '--abort']);
+    return { status: 'blocked', health: { ...health, fitsOnRemote: false, conflictFiles: unmerged.length > 0 ? unmerged : health.conflictFiles } };
+}
+/** The reply that picks "start from the remote's version". */
+export function parseBranchDirective(text) {
+    return /^\s*branch\s*[:=]\s*`?(start(ing)? fresh|fresh|(start from|use) (the )?(github|gitlab|bitbucket|remote|latest) version)`?[\s.!]*$/im.test(text || '')
+        ? 'fresh'
+        : null;
+}
+export const START_FRESH_REPLY = 'branch: start fresh';
+function commitLines(commits) {
+    const shown = commits.slice(0, 5).map((c) => `  - \`${c.sha}\` ${c.subject.slice(0, 90)}${c.date ? ` (${c.date})` : ''}`);
+    if (commits.length > shown.length)
+        shown.push(`  - and ${plural(commits.length - shown.length, 'more commit')}`);
+    return shown;
+}
+/** The question on the card when the folder is blocked before any work started. */
+export function describeBlockedBranch(health) {
+    const where = health.remoteLabel;
+    const lines = [
+        'I have not started on this card yet: the project folder on this computer needs a decision first.',
+        '',
+        `- ${where === 'the remote' ? 'The remote' : where} has ${plural(health.behind, 'newer commit')} on \`${health.branch}\` that this computer does not have.`,
+        `- This computer has ${plural(health.ahead, 'commit')} that ${health.ahead === 1 ? 'was' : 'were'} never pushed:`,
+        ...commitLines(health.unpushed),
+        health.conflictFiles.length > 0
+            ? `- The two clash in ${fileList(health.conflictFiles)}, so anything I build here could not be pushed.`
+            : '- The two do not fit together, so anything I build here could not be pushed.',
+        '',
+    ];
+    if (health.dirty) {
+        lines.push('There are also uncommitted changes in the folder, so I will not move anything myself.', `Please sort out the branch (commit or put away the changes, then merge or drop the unpushed ${health.ahead === 1 ? 'commit' : 'commits'}) and reply **retry**. I will check again and then do the card.`);
+        return { question: lines.join('\n'), options: [{ label: 'I fixed it, check again', reply: 'retry' }] };
+    }
+    lines.push('You can choose:', `- **Start from the ${where === 'the remote' ? 'remote' : where} version**: I keep ${health.ahead === 1 ? 'that commit' : `those ${health.ahead} commits`} safe on a backup branch (nothing is deleted), bring the folder up to date, and then do this card.`, '- **Sort it out yourself** (merge or drop those commits), then reply **retry** and I will check again.');
+    return {
+        question: lines.join('\n'),
+        options: [
+            { label: `Start from the ${where === 'the remote' ? 'remote' : where} version`, reply: START_FRESH_REPLY },
+            { label: 'I fixed it, check again', reply: 'retry' },
+        ],
+    };
+}
+const backupName = (branch) => `agilemonster/backup-${branch.replace(/[^A-Za-z0-9._-]+/g, '-')}-${new Date().toISOString().replace(/[-:]/g, '').replace(/\..*$/, '').replace('T', '-')}`;
+/**
+ * "Start from the remote's version": keep every unpushed commit on a backup branch, then make the local branch
+ * equal to the remote. Refuses when there are uncommitted changes, which a reset would destroy.
+ */
+export async function startFromRemote(cwd) {
+    const health = await inspectBranch(cwd);
+    if (!health.upstream || !health.branch)
+        return { ok: false, backup: '', setAside: 0, error: 'this branch does not exist on the remote' };
+    if (health.dirty)
+        return { ok: false, backup: '', setAside: 0, error: 'there are uncommitted changes in the project folder' };
+    const backup = backupName(health.branch);
+    const saved = await run(cwd, ['branch', backup, 'HEAD']);
+    if (!saved.ok)
+        return { ok: false, backup: '', setAside: 0, error: `could not create the backup branch: ${saved.tail.slice(0, 200)}` };
+    const reset = await run(cwd, ['reset', '--hard', health.upstream], 120000);
+    if (!reset.ok)
+        return { ok: false, backup, setAside: 0, error: `could not update the folder: ${reset.tail.slice(0, 200)}` };
+    log.info('branch.started_fresh', { project: cwd, branch: health.branch, backup, set_aside: health.ahead });
+    return { ok: true, backup, setAside: health.ahead };
+}
+export const cardTag = (cardId) => `[AM-${cardId.slice(0, 8)}]`;
+/** This card's commits, when they are the newest ones on the branch (the only shape that can be shipped alone). */
+function cardCommitsOnTop(unpushed, cardId) {
+    const tag = cardTag(cardId);
+    const mine = [];
+    let i = 0;
+    while (i < unpushed.length && unpushed[i].subject.includes(tag))
+        mine.push(unpushed[i++].sha);
+    if (unpushed.slice(i).some((c) => c.subject.includes(tag)))
+        return null; // interleaved with other work
+    return mine.reverse();
+}
+/** Work out, after a refused push, what actually clashes — the card, or older commits that were never pushed. */
+export async function explainPushConflict(cwd, cardId, unmergedFiles = []) {
+    const health = await inspectBranch(cwd, { fetch: false });
+    if (!health.upstream)
+        return null;
+    const mine = cardCommitsOnTop(health.unpushed, cardId);
+    const older = health.unpushed.filter((c) => !c.subject.includes(cardTag(cardId)));
+    let cardFitsAlone = null;
+    let files = unmergedFiles.length > 0 ? unmergedFiles : health.conflictFiles;
+    if (mine && mine.length > 0) {
+        if (older.length === 0) {
+            cardFitsAlone = false; // nothing else is unpushed: the card itself is what clashes
+        }
+        else {
+            const alone = await mergeFits(cwd, health.upstream, mine[mine.length - 1], `${mine[0]}^`);
+            cardFitsAlone = alone.fits;
+            if (alone.fits === false && alone.files.length > 0)
+                files = alone.files;
+        }
+    }
+    return {
+        branch: health.branch,
+        remoteLabel: health.remoteLabel,
+        behind: health.behind,
+        older,
+        cardCommits: mine || [],
+        conflictFiles: files,
+        cardFitsAlone,
+    };
+}
+export const ONLY_THIS_REPLY = 'deploy: only this change';
+/** Plain words for the card, the way out, and the buttons that take it. */
+export function describePushConflict(c) {
+    const where = c.remoteLabel;
+    const newer = `${where === 'the remote' ? 'The remote' : where} has ${plural(c.behind, 'newer commit')} on \`${c.branch}\``;
+    const inFiles = c.conflictFiles.length > 0 ? ` in ${fileList(c.conflictFiles)}` : '';
+    const fixed = { label: 'I fixed it, try again', reply: 'retry' };
+    const pushedYourself = 'If 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.';
+    if (c.older.length > 0 && c.cardFitsAlone !== false) {
+        const olderText = c.older.length === 1 ? '1 older commit that was never pushed, and it clashes' : `${c.older.length} older commits that were never pushed, and they clash`;
+        return {
+            detail: `The change is made and committed on this computer, but it could not be pushed. ${newer}. This computer also holds ${olderText} with the newer ones${inFiles}.` +
+                (c.cardFitsAlone ? " This card's own change is not the problem: it fits on top of the newer version by itself." : ''),
+            hint: [
+                `- **Ship only this change**: I put just this card's commit on top of the ${where === 'the remote' ? 'remote' : where} version and deploy it. The ${plural(c.older.length, 'older commit')} ${c.older.length === 1 ? 'stays' : 'stay'} safe on a backup branch, not deployed.`,
+                `- ${pushedYourself}`,
+            ].join('\n'),
+            options: [{ label: 'Ship only this change', reply: ONLY_THIS_REPLY }, fixed],
+        };
+    }
+    return {
+        detail: `The change is made and committed on this computer, but it could not be pushed. ${newer}, and they changed the same lines as this card${inFiles}: my change was built on an older version of the project.`,
+        hint: [
+            '- **Redo on the latest version**: I keep what I did on a backup branch, bring the folder up to date, and do the card again.',
+            `- ${pushedYourself}`,
+        ].join('\n'),
+        options: [{ label: 'Redo on the latest version', reply: START_FRESH_REPLY }, fixed],
+    };
+}
+/**
+ * "Ship only this change": keep the whole local branch on a backup branch, make the branch equal to the remote,
+ * and put only this card's commits back on top. If they do not apply, everything is put back as it was.
+ */
+export async function shipOnlyCardCommits(cwd, cardId) {
+    const none = { backup: '', setAside: 0 };
+    const health = await inspectBranch(cwd);
+    if (!health.upstream || !health.branch)
+        return { ok: false, ...none, error: 'this branch does not exist on the remote' };
+    if (health.dirty)
+        return { ok: false, ...none, error: 'there are uncommitted changes in the project folder' };
+    const mine = cardCommitsOnTop(health.unpushed, cardId);
+    if (!mine || mine.length === 0)
+        return { ok: false, ...none, error: "this card's commit is no longer the newest one on the branch" };
+    const setAside = health.unpushed.length - mine.length;
+    const original = (await run(cwd, ['rev-parse', 'HEAD'])).stdout.trim();
+    const backup = backupName(health.branch);
+    const saved = await run(cwd, ['branch', backup, 'HEAD']);
+    if (!saved.ok)
+        return { ok: false, ...none, error: `could not create the backup branch: ${saved.tail.slice(0, 200)}` };
+    const putBack = async (error) => {
+        await run(cwd, ['cherry-pick', '--abort']);
+        await run(cwd, ['reset', '--hard', original], 120000);
+        await run(cwd, ['branch', '-D', backup]);
+        return { ok: false, ...none, error };
+    };
+    const reset = await run(cwd, ['reset', '--hard', health.upstream], 120000);
+    if (!reset.ok)
+        return putBack(`could not update the folder: ${reset.tail.slice(0, 200)}`);
+    const pick = await run(cwd, ['cherry-pick', ...mine], 120000);
+    if (!pick.ok) {
+        const unmerged = (await run(cwd, ['diff', '--name-only', '--diff-filter=U'])).stdout.split(/\r?\n/).filter(Boolean);
+        return putBack(unmerged.length > 0 ? `this card's change itself clashes with the newer version in ${fileList(unmerged)}` : `this card's change did not apply on the newer version: ${pick.tail.slice(0, 200)}`);
+    }
+    log.info('branch.shipped_only_card', { project: cwd, branch: health.branch, backup, set_aside: setAside, picked: mine.length });
+    return { ok: true, backup, setAside };
+}

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 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.26";
+export declare const MCP_SERVER_VERSION = "1.0.27";
 export type QuestionOption = string | {
     label: string;
     reply: string;

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.26';
+export const MCP_SERVER_VERSION = '1.0.27';
 /** 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/deploy-memory.d.ts

@@ -50,6 +50,11 @@ export interface CardDeployState {
     at: string;
     attempts: number;
     last_error?: string | null;
+    /**
+     * Where the last attempt stopped. 'git' = the change never reached the remote, so a retry only has to push it
+     * (or find that a person already did) — it must not add an empty "redeploy" commit.
+     */
+    failed_stage?: 'git' | 'deploy' | null;
     /** Set when the agent asked "may I deploy with X?": a plain "yes"/"retry" then confirms X. */
     pending_confirmation?: {
         method: string;
@@ -89,6 +94,13 @@ export interface ProjectMemory {
         method: string;
         verified: boolean;
     }>;
+    /**
+     * Cards that are waiting for the owner to decide what to do with a branch that cannot be pushed
+     * (asked BEFORE any work started). Only a reply written after `at` answers the question.
+     */
+    branch_questions: Record<string, {
+        at: string;
+    }>;
 }
 export declare function memoryFileFor(projectPath: string): string;
 /**
@@ -118,5 +130,10 @@ export declare function setExplicitProfile(projectPath: string, explicit: {
 }): ProjectMemory;
 export declare function setCardState(projectPath: string, cardId: string, state: CardDeployState | null): void;
 export declare function getCardState(projectPath: string, cardId: string): CardDeployState | null;
+/** Remember (or, with null, forget) that this card is waiting for a decision about its branch. */
+export declare function setBranchQuestion(projectPath: string, cardId: string, at: string | null): void;
+export declare function getBranchQuestion(projectPath: string, cardId: string): {
+    at: string;
+} | null;
 export declare function addPendingVerification(projectPath: string, pending: PendingVerification): void;
 export declare function removePendingVerification(projectPath: string, cardId: string): void;

package/dist/deploy-memory.js

@@ -71,6 +71,7 @@ export function loadMemory(projectPath) {
                 pending: [],
                 cards: {},
                 deployed_cards: {},
+                branch_questions: {},
             };
             saveMemory(memory);
             return memory;
@@ -86,6 +87,7 @@ export function loadMemory(projectPath) {
         pending: Array.isArray(stored?.pending) ? stored.pending : [],
         cards: stored?.cards && typeof stored.cards === 'object' ? stored.cards : {},
         deployed_cards: stored?.deployed_cards && typeof stored.deployed_cards === 'object' ? stored.deployed_cards : {},
+        branch_questions: stored?.branch_questions && typeof stored.branch_questions === 'object' ? stored.branch_questions : {},
     };
 }
 export function saveMemory(memory) {
@@ -110,6 +112,10 @@ export function saveMemory(memory) {
             .slice(0, deployedIds.length - DEPLOYED_CARDS_LIMIT)
             .forEach((id) => delete memory.deployed_cards[id]);
     }
+    for (const id of Object.keys(memory.branch_questions)) {
+        if (Date.now() - (Date.parse(memory.branch_questions[id].at) || 0) > STALE_CARD_STATE_MS)
+            delete memory.branch_questions[id];
+    }
     memory.history = memory.history.slice(-HISTORY_LIMIT);
     try {
         writeJsonAtomic(memoryFileFor(memory.project_path), memory);
@@ -176,6 +182,20 @@ export function setCardState(projectPath, cardId, state) {
 export function getCardState(projectPath, cardId) {
     return loadMemory(projectPath).cards[cardId] || null;
 }
+/** Remember (or, with null, forget) that this card is waiting for a decision about its branch. */
+export function setBranchQuestion(projectPath, cardId, at) {
+    const memory = loadMemory(projectPath);
+    if (at)
+        memory.branch_questions[cardId] = { at };
+    else if (memory.branch_questions[cardId])
+        delete memory.branch_questions[cardId];
+    else
+        return;
+    saveMemory(memory);
+}
+export function getBranchQuestion(projectPath, cardId) {
+    return loadMemory(projectPath).branch_questions[cardId] || null;
+}
 export function addPendingVerification(projectPath, pending) {
     const memory = loadMemory(projectPath);
     memory.pending = memory.pending.filter((p) => p.card_id !== pending.card_id);

package/dist/deploy-runner.d.ts

@@ -1,5 +1,6 @@
 import { BoundProfile, DeployMethod, DeployProfile } from './deploy-profile.js';
 import { PendingVerification } from './deploy-memory.js';
+import { PushConflict } from './branch-health.js';
 /**
  * Runs a project's deployment and proves it worked.
  *
@@ -39,6 +40,12 @@ export interface DeployResult {
     commitHash: string;
     fullSha: string;
     branch: string;
+    /** The commit reached the remote in this attempt (or was already there). */
+    pushed: boolean;
+    /** Where a failed attempt stopped: 'git' = before the change reached the remote; 'deploy' = after. */
+    stage: 'git' | 'deploy' | null;
+    /** A refused push, worked out: what clashes and which ways out exist. */
+    conflict?: PushConflict;
     deployedNote: string;
     errorDetail: string;
     errorKind: string | null;
@@ -59,6 +66,8 @@ export interface DeployDirective {
     method: DeployMethod | null;
     command: string | null;
     liveUrl: string | null;
+    /** "Ship only this change": leave older unpushed commits out and push just this card's commit. */
+    onlyThis?: boolean;
 }
 /**
  * Parse a human reply to a "deployment failed / may I deploy with X?" question.

package/dist/deploy-runner.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { composeArgs, isRunnableCommand, methodLabel, normalizeMethod, pushPathsMatch, requiresConfirmation, resolveDeployProfile, } from './deploy-profile.js';
 import { loadMemory, recordAttempt } from './deploy-memory.js';
+import { describePushConflict, explainPushConflict } from './branch-health.js';
 import { ensureUserPath, exec, execShell, log, sleep, which } from './runtime.js';
 const FAILURE_TABLE = [
     [
@@ -69,6 +70,7 @@ export function classifyFailure(text) {
     }
     return { kind: 'unknown', hint: '', healable: false };
 }
+const ONLY_THIS_RE = /^(ship |push |deploy )?(only|just) this( one)?( change| card| commit)?$/i;
 const AFFIRMATIVE_RE = /^(retry|re-?deploy|try again|deploy again|go ahead|fixed|yes|yep|ok|okay|confirm(ed)?|do it)[\s.!]*$/i;
 /** A directive value only counts as a command when it starts like one — prose after "Deployment:" never runs. */
 const COMMAND_START_RE = /^(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:\.{1,2}\/|\/|~\/|(?:docker|docker-compose|make|npm|pnpm|yarn|npx|bun|bunx|node|deno|python3?|bash|sh|zsh|fly|flyctl|vercel|netlify|wrangler|firebase|gh|git|rsync|scp|ssh|ansible-playbook|kubectl|helm|terraform|cap|bundle|php|composer|gcloud|aws|az|heroku|task|just|cargo|go|dotnet|mvn|gradle|rake|fab|serverless|sls|cdk|pulumi)(?=\s|$))/;
@@ -91,7 +93,12 @@ export function parseDeployDirective(text) {
     if (directive) {
         const value = directive[1].replace(/^`+|`+$/g, '').trim();
         const asMethod = normalizeMethod(value);
-        if (AFFIRMATIVE_RE.test(value)) {
+        if (ONLY_THIS_RE.test(value.replace(/[\s.!]+$/, ''))) {
+            out.onlyThis = true;
+            out.retry = true;
+            matched = true;
+        }
+        else if (AFFIRMATIVE_RE.test(value)) {
             // "deploy: yes" confirms; it is not a program called `yes`
             out.retry = true;
             matched = true;
@@ -298,12 +305,21 @@ async function commitAndPush(req, profile, pushPolicy) {
                 push = await git(['push', state.remote, state.branch], 90000);
             }
             else {
+                const unmergedFiles = unmerged.split(/\r?\n/).filter(Boolean);
                 await git(['rebase', '--abort']);
+                // The raw Git output is for the log. The card gets what clashes, in words, and the ways out.
+                log.warn('deploy.rebase_conflict', { card: req.cardId, project: cwd, branch: state.branch, files: unmergedFiles, output: pull.tail.slice(0, 600) });
+                if (unmergedFiles.length === 0)
+                    return fail(pull, `Could not bring in the newer commits from ${state.remote}/${state.branch}`);
+                const conflict = await explainPushConflict(cwd, req.cardId, unmergedFiles);
                 return {
                     ...state,
                     ok: false,
                     errorKind: 'rebase_conflict',
-                    errorDetail: `The remote branch \`${state.branch}\` has new commits that conflict with this change, so it could not be pushed: ${pull.tail}`,
+                    conflict: conflict || undefined,
+                    errorDetail: conflict
+                        ? describePushConflict(conflict).detail
+                        : `The change is committed on this computer, but the remote branch \`${state.branch}\` has newer commits that clash with it in ${unmergedFiles.slice(0, 3).map((f) => `\`${f}\``).join(', ')}, so it could not be pushed.`,
                 };
             }
         }
@@ -959,6 +975,8 @@ export async function runDeployment(req) {
         commitHash: (git?.fullSha || '').slice(0, 7),
         fullSha: git?.fullSha || '',
         branch: git?.branch || '',
+        pushed: Boolean(git?.pushed),
+        stage: null,
         deployedNote: '',
         errorDetail: '',
         errorKind: null,
@@ -983,7 +1001,14 @@ export async function runDeployment(req) {
         const kind = git.errorKind || 'git';
         recordAttempt(req.projectPath, { card_id: req.cardId, method: profile.method, command: profile.command, ok: false, kind, error: git.errorDetail, duration_ms: Date.now() - startedAt });
         log.warn('deploy.git_failed', { card: req.cardId, project: req.projectPath, kind, error: git.errorDetail });
-        return result({ errorDetail: git.errorDetail || 'Git failed', errorKind: kind, hint: classifyFailure(git.errorDetail || '').hint || HINTS[kind] || '', healed: git.healed }, git);
+        return result({
+            errorDetail: git.errorDetail || 'Git failed',
+            errorKind: kind,
+            stage: 'git',
+            conflict: git.conflict,
+            hint: git.conflict ? describePushConflict(git.conflict).hint : classifyFailure(git.errorDetail || '').hint || HINTS[kind] || '',
+            healed: git.healed,
+        }, git);
     }
     let step = await runMethod(req, profile, git, changedFiles);
     const healed = [...git.healed, ...step.healed];
@@ -1019,6 +1044,7 @@ export async function runDeployment(req) {
         return result({
             errorDetail: step.errorDetail || 'Deployment failed',
             errorKind: kind,
+            stage: 'deploy',
             hint: HINTS[kind] || classifyFailure(step.errorDetail || '').hint,
             actions: [...git.actions, ...step.actions],
             healed,
@@ -1035,7 +1061,7 @@ export async function runDeployment(req) {
         else if (trusted) {
             const detail = `The deployment ran, but ${profile.liveUrl} returned ${status === 0 ? 'no response' : `HTTP ${status}`}.`;
             recordAttempt(req.projectPath, { card_id: req.cardId, method: profile.method, command: profile.command, ok: false, kind: 'live_check_failed', error: detail, commit: git.fullSha.slice(0, 7), duration_ms: Date.now() - startedAt });
-            return result({ errorDetail: detail, errorKind: 'live_check_failed', hint: 'Check the site, then reply "retry".', actions, healed }, git);
+            return result({ errorDetail: detail, errorKind: 'live_check_failed', stage: 'deploy', hint: 'Check the site, then reply "retry".', actions, healed }, git);
         }
     }
     // A human-pinned route is its own proof of intent; anything else only becomes "what worked" once verified
@@ -1097,6 +1123,19 @@ export function describeFailureForHuman(res) {
             `Or reply \`deploy: manual\` if you deploy this project yourself${others.length > 0 ? `, or pick another route I found: ${others.map((a) => `\`deploy: ${a.command || a.method}\``).join(', ')}` : ''}.`,
         ].join('\n');
     }
+    if (res.conflict) {
+        return [res.errorDetail, '', 'You can choose:', res.hint].join('\n');
+    }
+    if (res.stage === 'git') {
+        // The change never reached the remote. Which deploy route was picked is beside the point here:
+        // say what is in the way first, and keep Git's own words for whoever wants them.
+        const text = res.hint
+            ? [`The change is made, but Git stopped before it reached the remote. ${res.hint}`, '', `Technical detail: ${res.errorDetail.replace(/\s+/g, ' ').slice(0, 400)}`]
+            : [res.errorDetail.slice(0, 900)];
+        if (!/\bretry\b/i.test(text.join(' ')))
+            text.push('', 'Reply **retry** once it is fixed: I will not redo the work, only push it and check the deployment.');
+        return text.join('\n');
+    }
     const lines = [`What failed: ${res.errorDetail.slice(0, 900)}`];
     if (res.hint)
         lines.push('', res.hint);

package/dist/server.d.ts

@@ -2,6 +2,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { AgileMonsterClient, QuestionOption } from './client.js';
 import { ActiveClaim, Card } from './types.js';
 import { BoundProfile } from './deploy-profile.js';
+import { PushConflict } from './branch-health.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".
@@ -10,6 +11,8 @@ export declare function deployReplyOptions(res: {
     errorKind?: string | null;
     method?: string | null;
     command?: string | null;
+    stage?: 'git' | 'deploy' | null;
+    conflict?: PushConflict;
 }): QuestionOption[];
 export declare function createServer(client?: AgileMonsterClient): Server<{
     method: string;

package/dist/server.js

@@ -13,7 +13,8 @@ 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';
@@ -22,6 +23,11 @@ import { addWellKnownToolDirs, agileMonsterHome, configureLogger, ensureUserPath
  * 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 = [];
@@ -1673,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
@@ -1695,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.
@@ -1733,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,
     });
@@ -1751,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,
         });
@@ -1764,7 +1870,7 @@ 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)}`, deployReplyOptions(res));
         return 'failed';
@@ -2442,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 = {
@@ -2456,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,
         };
@@ -2520,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);
@@ -2536,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)}`, deployReplyOptions(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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilemonster/mcp-server",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "type": "module",
   "description": "Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)",
   "main": "dist/server.js",