@agilemonster/mcp-server 1.0.25 → 1.0.27

package/README.md

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

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

package/bin/orchestrator.js

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

package/dist/agent-engine.d.ts

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

package/dist/agent-engine.js

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

package/dist/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 };
+}