@agilemonster/mcp-server 1.0.16 → 1.0.21

package/dist/deploy-runner.js

@@ -0,0 +1,1108 @@
+import fs from 'node:fs';
+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 { ensureUserPath, exec, execShell, log, sleep, which } from './runtime.js';
+const FAILURE_TABLE = [
+    [
+        /cannot connect to the docker daemon|is the docker daemon running|docker daemon is not running|error during connect|docker desktop is not running/i,
+        'docker_daemon_down',
+        'Docker is installed but not running. Start Docker Desktop (or OrbStack) and reply "retry".',
+        true,
+    ],
+    [
+        /no configuration file provided|no such file or directory.*compose|compose.*not found|can't find a suitable configuration file/i,
+        'compose_missing',
+        'No Compose file was found where the deploy command expects one.',
+        false,
+    ],
+    [
+        /port is already allocated|address already in use|bind for .* failed/i,
+        'port_conflict',
+        'A port the container needs is already taken by another process or container. Stop the other one, then reply "retry".',
+        false,
+    ],
+    [
+        /non-fast-forward|fetch first|updates were rejected|\[rejected\]/i,
+        'non_fast_forward',
+        'The remote branch has commits this machine does not have yet.',
+        true,
+    ],
+    [
+        /protected branch|gh006|pre-receive hook declined|push declined/i,
+        'branch_protected',
+        'The branch is protected and does not accept direct pushes. Deploy from an unprotected branch or open a pull request.',
+        false,
+    ],
+    [
+        /permission denied \(publickey|host key verification failed|could not read from remote repository|authentication failed|could not read username|terminal prompts disabled|invalid credentials|bad credentials|http 401|http 403/i,
+        'auth',
+        'Credentials were rejected. Background agents cannot answer password prompts: make sure the SSH key is loaded in the agent/keychain (or `gh auth login` is done) for the user running the Agile Monster daemon.',
+        false,
+    ],
+    [
+        /please tell me who you are|unable to auto-detect email address|empty ident name/i,
+        'git_identity',
+        'Git has no user.name / user.email configured for this repository.',
+        false,
+    ],
+    [
+        /could not resolve host|connection timed out|connection reset|network is unreachable|tls handshake timeout|etimedout|econnreset|temporary failure in name resolution|unexpected eof|i\/o timeout/i,
+        'network',
+        'A network error interrupted the deployment.',
+        true,
+    ],
+    [/no space left on device/i, 'disk_full', 'The disk is full. Free up space (e.g. `docker system prune`) and reply "retry".', false],
+    [
+        /command not found|not recognized as an internal or external command|executable file not found|enoent/i,
+        'tool_missing',
+        'A tool the deployment needs is not installed (or not on the PATH of the background agent).',
+        false,
+    ],
+    [/timed out after/i, 'timeout', 'The deployment command did not finish in time.', false],
+];
+export function classifyFailure(text) {
+    for (const [re, kind, hint, healable] of FAILURE_TABLE) {
+        if (re.test(text))
+            return { kind, hint, healable };
+    }
+    return { kind: 'unknown', hint: '', healable: false };
+}
+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|$))/;
+/**
+ * Parse a human reply to a "deployment failed / may I deploy with X?" question.
+ * Returns null when the comment is not about deploying (it is then ordinary feedback on the code).
+ */
+export function parseDeployDirective(text) {
+    const clean = (text || '').trim();
+    if (!clean)
+        return null;
+    const out = { retry: false, method: null, command: null, liveUrl: null };
+    let matched = false;
+    const url = clean.match(/^\s*live\s*url\s*[:=]\s*`?(https?:\/\/[^\s`]+)`?\s*$/im);
+    if (url) {
+        out.liveUrl = url[1];
+        matched = true;
+    }
+    const directive = clean.match(/^\s*deploy(?:ment)?(?:\s+(?:with|via|using|method|command))?\s*[:=]\s*(.+?)\s*$/im);
+    if (directive) {
+        const value = directive[1].replace(/^`+|`+$/g, '').trim();
+        const asMethod = normalizeMethod(value);
+        if (AFFIRMATIVE_RE.test(value)) {
+            // "deploy: yes" confirms; it is not a program called `yes`
+            out.retry = true;
+            matched = true;
+        }
+        else if (asMethod) {
+            out.method = asMethod;
+            matched = true;
+        }
+        else if (COMMAND_START_RE.test(value)) {
+            out.command = value;
+            out.method = /^(?:\S+=\S*\s+)*docker(-compose|\s+compose)(\s|$)/i.test(value)
+                ? 'docker_compose'
+                : /^(npx\s+)?(vercel|netlify|wrangler|firebase)\b|^fly(ctl)?\s/i.test(value)
+                    ? 'cloud_cli'
+                    : /^gh\s+workflow\s+run\b/i.test(value)
+                        ? 'github_actions'
+                        : 'deploy_script';
+            matched = true;
+        }
+    }
+    if (clean.length < 60 && clean.split(/\r?\n/).some((line) => AFFIRMATIVE_RE.test(line.trim()))) {
+        out.retry = true;
+        matched = true;
+    }
+    if (out.method || out.liveUrl)
+        out.retry = true;
+    return matched ? out : null;
+}
+// ---------------------------------------------------------------------------
+// Git
+// ---------------------------------------------------------------------------
+const NEVER_COMMIT_RE = /(^|\/)(\.agilemonster\.json|\.mcp\.json|\.cursor\/mcp\.json|\.vscode\/mcp\.json|\.env(\.[\w.-]+)?|id_rsa|id_ed25519|.*\.pem|.*\.p12|\.agilemonster\/.*|\.git\/.*)$/i;
+/** Agent-modified paths that are safe to commit: inside the project, and never local config that carries secrets. */
+export function committablePaths(projectPath, files) {
+    const root = path.resolve(projectPath);
+    const out = [];
+    for (const f of files) {
+        const rel = f.replace(/\\/g, '/').replace(/^\.\//, '');
+        const isEnvTemplate = /(^|\/)\.env\.(example|sample|template|dist)$/i.test(rel);
+        if (!rel || (!isEnvTemplate && NEVER_COMMIT_RE.test(rel)))
+            continue;
+        const abs = path.resolve(root, rel);
+        if (!abs.startsWith(root + path.sep))
+            continue;
+        if (!out.includes(rel))
+            out.push(rel);
+    }
+    return out;
+}
+const LOCAL_EXCLUDES = ['.agilemonster/', '.agilemonster.json', '.agilemonster-task-*.lock', '.mcp.json', '.cursor/mcp.json', '.vscode/mcp.json', '.cursor/rules/agilemonster-queue.mdc'];
+/**
+ * Keep Agile Monster's local files (which contain the personal API key) out of every commit, by anyone,
+ * via the repository's `info/exclude` — a per-clone ignore list that is itself never committed.
+ * Works for worktrees and for a bound folder that is a sub-directory of a larger repository.
+ */
+export function ensureLocalGitExcludes(projectPath) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude', '--show-prefix'], {
+            cwd: projectPath,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).split(/\r?\n/);
+        const excludeRel = (out[0] || '').trim();
+        if (!excludeRel)
+            return;
+        const prefix = (out[1] || '').trim(); // e.g. "apps/web/" when the bound folder is inside a bigger repo
+        const file = path.resolve(projectPath, excludeRel);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        const lines = new Set(current.split(/\r?\n/).map((l) => l.trim()));
+        // Patterns containing an inner slash are anchored to the repository root, so they need the sub-folder prefix
+        const wanted = LOCAL_EXCLUDES.map((e) => (prefix && e.replace(/\/$/, '').includes('/') ? `/${prefix}${e}` : e));
+        const missing = wanted.filter((e) => !lines.has(e));
+        if (missing.length > 0) {
+            fs.appendFileSync(file, `${current.endsWith('\n') || current === '' ? '' : '\n'}# Agile Monster local agent files\n${missing.join('\n')}\n`, 'utf8');
+        }
+    }
+    catch {
+        // Not a Git repository (or git unavailable): nothing to protect.
+    }
+}
+async function commitAndPush(req, profile, pushPolicy) {
+    const cwd = req.projectPath;
+    const needsPush = pushPolicy === 'required';
+    const state = {
+        ok: true,
+        isRepo: false,
+        branch: '',
+        fullSha: '',
+        committed: false,
+        pushed: false,
+        remote: '',
+        actions: [],
+        healed: [],
+    };
+    // `--literal-pathspecs`: a path like app/[id]/page.tsx is that one file, never a glob over the developer's others
+    const git = (args, timeoutMs = 45000) => exec('git', ['--literal-pathspecs', ...args], { cwd, timeoutMs });
+    state.isRepo = (await git(['rev-parse', '--is-inside-work-tree'])).stdout.trim() === 'true';
+    if (!state.isRepo) {
+        state.actions.push('project folder is not a Git repository (nothing committed)');
+        return state;
+    }
+    const fail = (res, what) => {
+        const cls = classifyFailure(res.tail);
+        return { ...state, ok: false, errorKind: cls.kind === 'unknown' ? 'git' : cls.kind, errorDetail: `${what}: ${res.tail}` };
+    };
+    ensureLocalGitExcludes(cwd);
+    state.branch = (await git(['branch', '--show-current'])).stdout.trim();
+    const files = committablePaths(cwd, req.files || []);
+    if (files.length > 0) {
+        if (!state.branch) {
+            return {
+                ...state,
+                ok: false,
+                errorKind: 'detached_head',
+                errorDetail: 'The repository is in a detached-HEAD state, so there is no branch to commit the change to. Check out a branch and reply "retry".',
+            };
+        }
+        const staged = [];
+        for (const f of files) {
+            let add = await git(['add', '-A', '--', f]);
+            // Editors and IDE Git integrations hold index.lock for moments at a time
+            for (let attempt = 0; attempt < 3 && !add.ok && /index\.lock/i.test(add.tail); attempt++) {
+                await sleep(2000);
+                add = await git(['add', '-A', '--', f]);
+            }
+            if (add.ok) {
+                staged.push(f);
+                continue;
+            }
+            const ignored = await git(['check-ignore', '-q', '--', f]);
+            if (ignored.code === 0) {
+                state.actions.push(`note: \`${f}\` is ignored by Git and was not committed`);
+                continue;
+            }
+            // A change that cannot be staged must never be reported as shipped
+            return fail(add, `Could not stage \`${f}\` for commit`);
+        }
+        if (staged.length > 0) {
+            const dirty = await git(['status', '--porcelain', '--', ...staged]);
+            if (dirty.stdout.trim().length > 0) {
+                const title = (req.title || 'update').replace(/[\r\n]+/g, ' ').trim().slice(0, 120);
+                // `--only -- <paths>` commits exactly these files even if the developer has other things staged.
+                const commit = await git(['commit', '--only', '-m', `feat: ${title} [AM-${req.cardId.slice(0, 8)}]`, '--', ...staged], 120000);
+                if (!commit.ok) {
+                    const res = fail(commit, 'Git commit failed');
+                    if (/hook/i.test(commit.tail) && res.errorKind === 'git')
+                        res.errorKind = 'commit_hook';
+                    return res;
+                }
+                state.committed = true;
+            }
+        }
+    }
+    state.fullSha = (await git(['rev-parse', 'HEAD'])).stdout.trim();
+    const short = state.fullSha.slice(0, 7);
+    if (pushPolicy === 'none') {
+        state.actions.push(state.committed ? `committed \`${short}\` locally (not pushed)` : 'nothing new to commit');
+        return state;
+    }
+    const remotes = (await git(['remote'])).stdout.split(/\s+/).filter(Boolean);
+    if (remotes.length === 0) {
+        state.actions.push(state.committed ? `committed \`${short}\` locally (no Git remote configured)` : 'no Git remote configured');
+        return state;
+    }
+    if (!state.branch) {
+        state.actions.push('detached HEAD: nothing pushed');
+        return state;
+    }
+    const configured = (await git(['config', '--get', `branch.${state.branch}.remote`])).stdout.trim();
+    state.remote = configured && remotes.includes(configured) ? configured : remotes.includes('origin') ? 'origin' : remotes[0];
+    // A push-triggered pipeline needs a new commit to react to when the human asks for a re-deploy.
+    if (req.redeploy && !state.committed && needsPush && !profile.dispatchOnly) {
+        const ahead = (await git(['rev-list', '--count', `${state.remote}/${state.branch}..HEAD`])).stdout.trim();
+        if (ahead === '0') {
+            const empty = await git(['commit', '--allow-empty', '-m', `chore: trigger redeploy [AM-${req.cardId.slice(0, 8)}]`]);
+            if (empty.ok) {
+                state.committed = true;
+                state.fullSha = (await git(['rev-parse', 'HEAD'])).stdout.trim();
+            }
+        }
+    }
+    let push = await git(['push', state.remote, state.branch], 90000);
+    if (!push.ok) {
+        let cls = classifyFailure(push.tail);
+        if (cls.kind === 'non_fast_forward' && needsPush) {
+            // Only rebase automatically when nothing of the developer's is in flight: with uncommitted edits, an
+            // autostash rebase can leave conflict markers in their files.
+            const inFlight = (await git(['status', '--porcelain', '--untracked-files=no'])).stdout.trim();
+            if (inFlight.length > 0) {
+                return {
+                    ...state,
+                    ok: false,
+                    errorKind: 'remote_ahead',
+                    errorDetail: `The remote branch \`${state.branch}\` has new commits, and this working tree has other uncommitted changes, so I did not rebase automatically. Run \`git pull --rebase\` in the project and reply "retry".`,
+                };
+            }
+            const pull = await git(['pull', '--rebase', state.remote, state.branch], 120000);
+            const unmerged = (await git(['diff', '--name-only', '--diff-filter=U'])).stdout.trim();
+            if (pull.ok && !unmerged) {
+                state.healed.push(`remote \`${state.branch}\` had new commits: rebased onto them and pushed again`);
+                state.fullSha = (await git(['rev-parse', 'HEAD'])).stdout.trim();
+                push = await git(['push', state.remote, state.branch], 90000);
+            }
+            else {
+                await git(['rebase', '--abort']);
+                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}`,
+                };
+            }
+        }
+        else if (cls.kind === 'network') {
+            await sleep(8000);
+            push = await git(['push', state.remote, state.branch], 90000);
+            if (push.ok)
+                state.healed.push('push succeeded on retry after a network error');
+        }
+        if (!push.ok) {
+            cls = classifyFailure(push.tail);
+            if (!needsPush) {
+                state.actions.push(`push to \`${state.remote}/${state.branch}\` skipped (${cls.kind === 'unknown' ? 'remote not reachable' : cls.kind.replace(/_/g, ' ')}); continuing with the local deployment`);
+                return state;
+            }
+            return fail(push, `git push to ${state.remote}/${state.branch} failed`);
+        }
+    }
+    state.pushed = true;
+    state.actions.push(`pushed \`${state.fullSha.slice(0, 7)}\` to \`${state.remote}/${state.branch}\``);
+    return state;
+}
+const CI_OK = new Set(['success', 'skipped', 'neutral']);
+const DEPLOYISH_RE = /deploy|release|publish|cpanel|pages|production|ship/i;
+const runLabel = (r) => r.workflowName || r.name || 'workflow';
+/** Re-runs and dispatch retries leave several runs per workflow for one commit: only the newest one counts. */
+function latestPerWorkflow(runs) {
+    const newest = new Map();
+    for (const r of runs) {
+        const key = runLabel(r).toLowerCase();
+        const prev = newest.get(key);
+        // `gh run list` returns newest first, so the first one seen wins unless timestamps say otherwise
+        if (!prev || (Date.parse(r.createdAt || '') || 0) > (Date.parse(prev.createdAt || '') || Number.MAX_SAFE_INTEGER)) {
+            newest.set(key, r);
+        }
+    }
+    return Array.from(newest.values());
+}
+/**
+ * Decide what a commit's workflow runs say about the DEPLOYMENT.
+ * A failing lint/test workflow does not mean the deploy failed (unless the deploy is chained behind it),
+ * a deploy that has not finished is "pending", and a run cancelled by a newer one is neither success nor failure.
+ *
+ * `deployNames` may hold workflow names and/or workflow file paths (GitHub reports a workflow without a
+ * `name:` by its path).
+ */
+export function judgeCiRuns(runs, deployNames, chainedDeploy = false) {
+    const warnings = [];
+    const latest = latestPerWorkflow(runs);
+    if (latest.length === 0)
+        return { verdict: 'none', warnings };
+    const names = deployNames.map((n) => n.toLowerCase());
+    let deployRuns = names.length > 0 ? latest.filter((r) => names.includes(runLabel(r).toLowerCase())) : latest.filter((r) => DEPLOYISH_RE.test(runLabel(r)));
+    // Nothing tells us which run is the deployment: then every run has to pass
+    if (names.length === 0 && deployRuns.length === 0)
+        deployRuns = latest;
+    const others = latest.filter((r) => !deployRuns.includes(r));
+    if (deployRuns.length > 0) {
+        const failed = deployRuns.find((r) => r.status === 'completed' && !CI_OK.has(r.conclusion || '') && r.conclusion !== 'cancelled');
+        if (failed) {
+            return { verdict: 'failure', failed, reason: `"${runLabel(failed)}" ended with ${failed.conclusion || 'an error'}`, warnings, url: failed.url };
+        }
+        if (deployRuns.some((r) => r.status !== 'completed')) {
+            return { verdict: 'pending', warnings, url: deployRuns.find((r) => r.status !== 'completed')?.url };
+        }
+        for (const o of others) {
+            if (o.status === 'completed' && !CI_OK.has(o.conclusion || '')) {
+                warnings.push(`"${runLabel(o)}" ${o.conclusion} (not part of the deployment): ${o.url || ''}`.trim());
+            }
+        }
+        const succeeded = deployRuns.filter((r) => r.conclusion === 'success' || r.conclusion === 'neutral');
+        if (succeeded.length === 0) {
+            const sample = deployRuns[0];
+            const why = sample.conclusion === 'cancelled' ? 'was cancelled (usually superseded by a newer run)' : 'was skipped for this commit';
+            return { verdict: 'no_deploy_run', reason: `"${runLabel(sample)}" ${why}`, warnings, url: sample.url };
+        }
+        return { verdict: 'success', warnings, url: succeeded[0].url };
+    }
+    if (others.some((r) => r.status !== 'completed')) {
+        return { verdict: 'pending', warnings, url: others.find((r) => r.status !== 'completed')?.url };
+    }
+    const failedOther = others.find((r) => !CI_OK.has(r.conclusion || '') && r.conclusion !== 'cancelled');
+    if (failedOther && chainedDeploy) {
+        return {
+            verdict: 'failure',
+            failed: failedOther,
+            reason: `"${runLabel(failedOther)}" ${failedOther.conclusion}, so the deployment that runs after it never started`,
+            warnings,
+            url: failedOther.url,
+        };
+    }
+    if (failedOther)
+        warnings.push(`"${runLabel(failedOther)}" ${failedOther.conclusion}: ${failedOther.url || ''}`.trim());
+    return { verdict: 'no_deploy_run', warnings };
+}
+async function fetchRuns(cwd, args) {
+    const res = await exec('gh', ['run', 'list', ...args, '--json', 'databaseId,status,conclusion,name,workflowName,url,event,createdAt', '--limit', '20'], { cwd, timeoutMs: 25000 });
+    if (!res.ok)
+        return { runs: [], error: res.tail };
+    try {
+        return { runs: JSON.parse(res.stdout || '[]') };
+    }
+    catch {
+        return { runs: [], error: 'gh returned unreadable output' };
+    }
+}
+async function failedLogTail(cwd, run) {
+    if (!run?.databaseId)
+        return '';
+    const res = await exec('gh', ['run', 'view', String(run.databaseId), '--log-failed'], { cwd, timeoutMs: 40000 });
+    if (!res.ok || !res.stdout.trim())
+        return '';
+    return res.stdout
+        .split('\n')
+        .map((l) => l.replace(/^\S+\t[^\t]*\t\S+Z\s?/, '').trim())
+        .filter((l) => l.length > 0 && /error|fail|denied|fatal|exception|not found|exit code/i.test(l))
+        .slice(-6)
+        .join(' | ')
+        .slice(0, 700);
+}
+/** Names GitHub may report for a workflow: its `name:`, or its path when it has none. */
+export function workflowMatchNames(workflows) {
+    return Array.from(new Set(workflows.flatMap((w) => [w.name, `.github/workflows/${w.file}`])));
+}
+/** Re-check a commit's runs once (used both inline and for deferred verification on later pulses). */
+export async function checkCiOnce(cwd, sha, deployNames, chained) {
+    const { runs, error } = await fetchRuns(cwd, ['--commit', sha]);
+    if (error)
+        return { verdict: 'none', warnings: [], ghError: error };
+    const verdict = judgeCiRuns(runs, deployNames, chained);
+    if (verdict.verdict === 'failure') {
+        return { ...verdict, logTail: await failedLogTail(cwd, verdict.failed) };
+    }
+    return verdict;
+}
+const shQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+async function verifyGithubActions(req, profile, git, changedFiles) {
+    const cwd = req.projectPath;
+    const actions = [];
+    const deployWfs = profile.workflows.filter((w) => w.isDeploy);
+    const candidateWfs = deployWfs.length > 0 ? deployWfs : profile.workflows;
+    const deployNames = workflowMatchNames(deployWfs);
+    const chained = deployWfs.some((w) => w.workflowRun);
+    const short = git.fullSha.slice(0, 7);
+    const unverified = (text, extra = []) => ({ ok: true, unverified: true, actions: [...actions, text, ...extra], healed: [] });
+    if (!which('gh')) {
+        return unverified('GitHub Actions should have been triggered by the push, but that could not be verified: the `gh` CLI is not installed on this machine');
+    }
+    // A dispatch is either what the project needs (deploy workflow with no push trigger) or what the human asked
+    // for with an explicit `gh workflow run <file>` command — in which case exactly that workflow is started.
+    const explicitDispatch = (profile.command || '').match(/^gh\s+workflow\s+run\s+("[^"]+"|'[^']+'|\S+)/i);
+    const dispatchFile = explicitDispatch
+        ? path.basename(explicitDispatch[1].replace(/^["']|["']$/g, ''))
+        : profile.dispatchOnly
+            ? (candidateWfs.find((w) => w.dispatch) || candidateWfs[0])?.file || ''
+            : '';
+    let dispatchedAt = 0;
+    if (explicitDispatch || profile.dispatchOnly) {
+        if (!dispatchFile)
+            return { ok: false, actions, healed: [], errorKind: 'no_workflow', errorDetail: 'No dispatchable deploy workflow was found.', wrongMethod: true };
+        dispatchedAt = Date.now();
+        const dispatch = explicitDispatch
+            ? await execShell(/\s--ref[\s=]/.test(profile.command || '') ? profile.command : `${profile.command} --ref ${shQuote(git.branch)}`, { cwd, timeoutMs: 30000 })
+            : await exec('gh', ['workflow', 'run', dispatchFile, '--ref', git.branch], { cwd, timeoutMs: 30000 });
+        if (!dispatch.ok) {
+            const cls = classifyFailure(dispatch.tail);
+            return { ok: false, actions, healed: [], errorKind: cls.kind === 'unknown' ? 'dispatch_failed' : cls.kind, errorDetail: `Could not start the \`${dispatchFile}\` workflow: ${dispatch.tail}` };
+        }
+        actions.push(`started the \`${dispatchFile}\` workflow on \`${git.branch}\``);
+    }
+    const waitMs = req.ciWaitMs ?? 8 * 60 * 1000;
+    const startedAt = Date.now();
+    const deadline = startedAt + waitMs;
+    let last = null;
+    let quietSince = 0;
+    await sleep(Math.min(6000, waitMs));
+    while (Date.now() < deadline) {
+        if (dispatchFile) {
+            const { runs, error } = await fetchRuns(cwd, ['--workflow', dispatchFile, '--event', 'workflow_dispatch']);
+            const mine = runs.filter((r) => Date.parse(r.createdAt || '') >= dispatchedAt - 15000).slice(0, 1);
+            // The single run we just started IS the deployment, whatever it is called
+            last = error ? { verdict: 'none', warnings: [], ghError: error } : judgeCiRuns(mine, mine.map(runLabel), false);
+            if (last.verdict === 'failure')
+                last.logTail = await failedLogTail(cwd, last.failed);
+        }
+        else {
+            last = await checkCiOnce(cwd, git.fullSha, deployNames, chained);
+        }
+        if (last.ghError && /auth|login|401|403|not logged/i.test(last.ghError)) {
+            return unverified('GitHub Actions should have been triggered, but that could not be verified: `gh` is not signed in on this machine (run `gh auth login`)');
+        }
+        if (last.verdict === 'success' || last.verdict === 'failure')
+            break;
+        if (last.verdict === 'none' && Date.now() - startedAt > 90000)
+            break;
+        if (last.verdict === 'no_deploy_run') {
+            // A chained deploy (workflow_run) appears a little after its upstream finishes; give it time.
+            quietSince = quietSince || Date.now();
+            if (!chained || Date.now() - quietSince > 120000)
+                break;
+        }
+        else {
+            quietSince = 0;
+        }
+        await sleep(12000);
+    }
+    const verdict = last?.verdict || 'none';
+    const warn = (last?.warnings || []).map((w) => `note: ${w}`);
+    if (verdict === 'success') {
+        return { ok: true, actions: [...actions, `GitHub Actions deployment passed for \`${short}\`${last?.url ? ` (${last.url})` : ''}`, ...warn], healed: [] };
+    }
+    if (verdict === 'failure') {
+        return {
+            ok: false,
+            actions,
+            healed: [],
+            errorKind: 'ci_failed',
+            runUrl: last?.url,
+            errorDetail: `GitHub Actions: ${last?.reason || 'the deployment workflow failed'} for commit ${short}. ${last?.url || ''}${last?.logTail ? `\nFailing step output: ${last.logTail}` : ''}`.trim(),
+        };
+    }
+    if (verdict === 'pending' && !dispatchFile) {
+        return {
+            ok: true,
+            pending: true,
+            actions: [...actions, `GitHub Actions is still deploying \`${short}\`${last?.url ? ` (${last.url})` : ''} — I will confirm on this card when it finishes`],
+            healed: [],
+            runUrl: last?.url,
+            workflowNames: deployNames,
+        };
+    }
+    if (verdict === 'pending') {
+        return unverified(`the \`${dispatchFile}\` workflow was still running when I stopped waiting${last?.url ? ` (${last.url})` : ''} — check it before approving`);
+    }
+    // No deploy run for this commit: say so plainly. This is never recorded as a verified deployment.
+    const pushDeploys = candidateWfs.filter((w) => w.push);
+    const filtered = !dispatchFile && pushDeploys.length > 0 && pushDeploys.every((w) => !pushPathsMatch(w.push, changedFiles));
+    if (filtered) {
+        const paths = pushDeploys.flatMap((w) => w.push?.paths || []).slice(0, 5).join(', ');
+        return unverified(`no deployment ran because the changed files are outside the deploy workflow's path filter (${paths})`, warn);
+    }
+    if (last?.reason) {
+        return unverified(`no deployment ran: ${last.reason}`, warn);
+    }
+    return unverified(`no GitHub Actions deployment run appeared for \`${short}\` (check that Actions are enabled and the workflow triggers on \`${git.branch}\`)`, warn);
+}
+/** `docker compose ps --format json` prints either one JSON array or one object per line, depending on the version. */
+export function parseComposePsJson(text) {
+    const trimmed = (text || '').trim();
+    if (!trimmed)
+        return [];
+    try {
+        const parsed = JSON.parse(trimmed);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch { }
+    const out = [];
+    for (const line of trimmed.split(/\r?\n/)) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { }
+    }
+    return out;
+}
+export function evaluateComposePs(entries) {
+    const bad = [];
+    let settling = false;
+    let running = 0;
+    for (const e of entries) {
+        const state = (e.State || '').toLowerCase();
+        const health = (e.Health || '').toLowerCase();
+        if (state === 'running')
+            running++;
+        if (state === 'dead' || state === 'restarting' || health === 'unhealthy')
+            bad.push(e);
+        else if (state === 'exited' && (e.ExitCode ?? 0) !== 0)
+            bad.push(e);
+        else if (state === 'created' || health === 'starting')
+            settling = true;
+    }
+    return { ok: bad.length === 0 && running > 0, settling, bad, running };
+}
+/** Map changed files to the Compose services that must be rebuilt or restarted (from `docker compose config --format json`). */
+export function planComposeRefresh(config, composeDir, changedAbs) {
+    const plan = { rebuild: [], restart: [], all: false };
+    const services = config?.services && typeof config.services === 'object' ? config.services : null;
+    if (!services || changedAbs.length === 0)
+        return { ...plan, all: true };
+    const inside = (file, dir) => {
+        const d = path.resolve(dir);
+        return file === d || file.startsWith(d + path.sep);
+    };
+    for (const [name, svc] of Object.entries(services)) {
+        const build = svc?.build;
+        const context = typeof build === 'string' ? build : build?.context;
+        if (context) {
+            const ctxAbs = path.isAbsolute(context) ? context : path.resolve(composeDir, context);
+            if (changedAbs.some((f) => inside(f, ctxAbs))) {
+                plan.rebuild.push(name);
+                continue;
+            }
+        }
+        const volumes = Array.isArray(svc?.volumes) ? svc.volumes : [];
+        for (const v of volumes) {
+            const source = typeof v === 'string' ? v.split(':')[0] : v?.type === 'bind' ? v.source : null;
+            if (!source || (!path.isAbsolute(source) && !source.startsWith('.')))
+                continue;
+            const srcAbs = path.isAbsolute(source) ? source : path.resolve(composeDir, source);
+            if (changedAbs.some((f) => inside(f, srcAbs))) {
+                plan.restart.push(name);
+                break;
+            }
+        }
+    }
+    if (plan.rebuild.length === 0 && plan.restart.length === 0)
+        plan.all = true;
+    return plan;
+}
+async function dockerReady(cwd) {
+    return exec('docker', ['info', '--format', '{{.ServerVersion}}'], { cwd, timeoutMs: 15000 });
+}
+async function startDockerDesktop() {
+    if (process.platform !== 'darwin')
+        return null;
+    const apps = ['/Applications/OrbStack.app', '/Applications/Docker.app'].filter((p) => fs.existsSync(p));
+    if (apps.length === 0)
+        return null;
+    const context = await exec('docker', ['context', 'show'], { timeoutMs: 5000 });
+    const preferOrb = /orbstack/i.test(context.stdout) && apps.some((a) => a.includes('OrbStack'));
+    const app = preferOrb ? '/Applications/OrbStack.app' : apps.find((a) => a.includes('Docker')) || apps[0];
+    const opened = await exec('open', ['-ga', app], { timeoutMs: 10000 });
+    return opened.ok ? path.basename(app, '.app') : null;
+}
+function composeTargetFromCommand(command) {
+    const files = [];
+    let projectName = null;
+    const tokens = command.match(/"[^"]*"|'[^']*'|\S+/g) || [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        const next = (tokens[i + 1] || '').replace(/^["']|["']$/g, '');
+        if ((t === '-f' || t === '--file') && next)
+            files.push(next);
+        else if (t.startsWith('--file='))
+            files.push(t.slice(7));
+        else if ((t === '-p' || t === '--project-name') && next)
+            projectName = next;
+        else if (t === 'up' || t === 'restart' || t === 'build')
+            break;
+    }
+    return { projectName, files, running: false };
+}
+async function deployDockerCompose(req, profile, changedFiles) {
+    const cwd = req.projectPath;
+    const actions = [];
+    const healed = [];
+    if (!which('docker')) {
+        await ensureUserPath(true);
+        if (!which('docker')) {
+            return {
+                ok: false,
+                actions,
+                healed,
+                errorKind: 'tool_missing',
+                wrongMethod: true,
+                errorDetail: 'Docker is not installed on this machine (the `docker` command was not found), so a local Docker Compose deployment cannot run here.',
+            };
+        }
+    }
+    let ready = await dockerReady(cwd);
+    if (!ready.ok) {
+        const started = await startDockerDesktop();
+        if (started) {
+            for (let i = 0; i < 24 && !ready.ok; i++) {
+                await sleep(5000);
+                ready = await dockerReady(cwd);
+            }
+            if (ready.ok)
+                healed.push(`Docker was not running: started ${started} and waited for it to come up`);
+        }
+        if (!ready.ok) {
+            return {
+                ok: false,
+                actions,
+                healed,
+                errorKind: 'docker_daemon_down',
+                errorDetail: `Docker is installed but not running${started ? ` (tried starting ${started}, but it did not become ready)` : ''}: ${ready.tail}`,
+            };
+        }
+    }
+    const custom = isRunnableCommand(profile.command) && !profile.compose ? profile.command : null;
+    const target = profile.compose || (custom ? composeTargetFromCommand(custom) : { projectName: null, files: [], running: false });
+    const base = composeArgs(target);
+    const compose = (args, timeoutMs = 60000) => exec('docker', [...base, ...args], { cwd, timeoutMs });
+    const before = parseComposePsJson((await compose(['ps', '-a', '--format', 'json'])).stdout);
+    const idsBefore = new Map(before.map((e) => [e.Service || e.Name || '', e.ID || '']));
+    let plan = { rebuild: [], restart: [], all: true };
+    const cfg = await compose(['config', '--format', 'json'], 30000);
+    if (!custom && !cfg.ok && classifyFailure(cfg.tail).kind === 'compose_missing') {
+        return { ok: false, actions, healed, errorKind: 'compose_missing', wrongMethod: true, errorDetail: `No Compose file could be loaded for this project: ${cfg.tail}` };
+    }
+    if (cfg.ok && changedFiles.length > 0) {
+        try {
+            const firstFile = target.files[0] ? path.resolve(cwd, target.files[0]) : path.join(cwd, 'compose.yaml');
+            plan = planComposeRefresh(JSON.parse(cfg.stdout), path.dirname(firstFile), changedFiles.map((f) => path.resolve(cwd, f)));
+        }
+        catch { }
+    }
+    const BUILD_TIMEOUT = 20 * 60 * 1000;
+    let up;
+    if (custom) {
+        up = await execShell(custom, { cwd, timeoutMs: BUILD_TIMEOUT });
+    }
+    else if (plan.all) {
+        up = await compose(['up', '-d', '--build'], BUILD_TIMEOUT);
+    }
+    else if (plan.rebuild.length > 0) {
+        up = await compose(['up', '-d', '--build', ...plan.rebuild], BUILD_TIMEOUT);
+    }
+    else {
+        up = await compose(['up', '-d'], BUILD_TIMEOUT);
+    }
+    // `compose up --build` is idempotent, so a network hiccup during an image pull is safe to retry.
+    // A human-supplied command is never re-run automatically.
+    if (!custom && !up.ok && classifyFailure(up.tail).kind === 'network') {
+        await sleep(10000);
+        up = await compose(['up', '-d', '--build', ...(plan.all ? [] : plan.rebuild)], BUILD_TIMEOUT);
+        if (up.ok)
+            healed.push('Docker build succeeded on retry after a network error');
+    }
+    if (!up.ok) {
+        const cls = classifyFailure(up.tail);
+        return {
+            ok: false,
+            actions,
+            healed,
+            errorKind: cls.kind === 'unknown' ? 'docker_build_failed' : cls.kind,
+            wrongMethod: cls.kind === 'compose_missing',
+            errorDetail: `Docker Compose could not rebuild/start the containers: ${up.tail}`,
+        };
+    }
+    if (!custom && !plan.all && plan.restart.length > 0) {
+        const restart = await compose(['restart', ...plan.restart], 120000);
+        if (!restart.ok) {
+            return { ok: false, actions, healed, errorKind: 'docker_restart_failed', errorDetail: `Could not restart ${plan.restart.join(', ')}: ${restart.tail}` };
+        }
+    }
+    // Verify: every container up (or cleanly finished), health checks passing.
+    // A container that was already dead before this deploy and was not touched by it (same ID) is reported,
+    // not blamed on the deploy.
+    const brokenBefore = new Set(evaluateComposePs(before).bad.map((e) => e.ID || '').filter(Boolean));
+    let entries = [];
+    let verdict = evaluateComposePs(entries);
+    let leftovers = [];
+    for (let i = 0; i < 18; i++) {
+        entries = parseComposePsJson((await compose(['ps', '-a', '--format', 'json'])).stdout);
+        leftovers = entries.filter((e) => brokenBefore.has(e.ID || ''));
+        verdict = evaluateComposePs(entries.filter((e) => !brokenBefore.has(e.ID || '')));
+        if (verdict.bad.length > 0)
+            break;
+        if (!verdict.settling) {
+            // "Running" one second after start proves little: a container that crashes on boot looks fine at first.
+            // Require it to still be healthy a few seconds later.
+            await sleep(6000);
+            const again = parseComposePsJson((await compose(['ps', '-a', '--format', 'json'])).stdout);
+            const recheck = evaluateComposePs(again.filter((e) => !brokenBefore.has(e.ID || '')));
+            entries = again;
+            verdict = recheck;
+            if (recheck.bad.length > 0 || !recheck.settling)
+                break;
+        }
+        await sleep(5000);
+    }
+    if (!verdict.ok) {
+        const culprit = verdict.bad[0];
+        const svc = culprit?.Service || culprit?.Name || '';
+        const logs = svc ? await compose(['logs', '--no-color', '--tail', '25', svc], 20000) : null;
+        const why = culprit
+            ? `container \`${svc}\` is ${culprit.Health === 'unhealthy' ? 'unhealthy' : culprit.State}${culprit.ExitCode ? ` (exit code ${culprit.ExitCode})` : ''}`
+            : 'no containers are running after the deploy';
+        return {
+            ok: false,
+            actions,
+            healed,
+            errorKind: 'container_unhealthy',
+            errorDetail: `Docker Compose finished, but ${why}.${logs?.stdout ? `\nLast log lines: ${logs.stdout.split('\n').map((l) => l.trim()).filter(Boolean).slice(-6).join(' | ').slice(0, 600)}` : ''}`,
+        };
+    }
+    const recreated = entries
+        .filter((e) => (e.State || '').toLowerCase() === 'running')
+        .map((e) => e.Service || e.Name || '')
+        .filter((svc) => svc && idsBefore.get(svc) !== entries.find((e) => (e.Service || e.Name) === svc)?.ID);
+    const parts = [];
+    if (recreated.length > 0)
+        parts.push(`recreated ${recreated.map((s) => `\`${s}\``).join(', ')} from a fresh build`);
+    if (!plan.all && plan.restart.length > 0)
+        parts.push(`restarted ${plan.restart.map((s) => `\`${s}\``).join(', ')}`);
+    if (parts.length === 0)
+        parts.push('images were already up to date, containers left running');
+    actions.push(`Docker Compose${target.projectName ? ` project \`${target.projectName}\`` : ''}: ${parts.join('; ')} (${verdict.running} running)`);
+    if (leftovers.length > 0) {
+        actions.push(`note: ${leftovers.map((e) => `\`${e.Service || e.Name}\``).join(', ')} was already stopped with an error before this deploy and was left as is`);
+    }
+    const port = entries.flatMap((e) => e.Publishers || []).map((p) => p.PublishedPort || 0).find((p) => p > 0);
+    if (port) {
+        const status = await httpStatus(`http://localhost:${port}`, 5000);
+        if (status > 0)
+            actions.push(`responding on http://localhost:${port} (HTTP ${status})`);
+    }
+    return { ok: true, actions, healed };
+}
+// ---------------------------------------------------------------------------
+// Scripts / cloud CLIs, smoke check
+// ---------------------------------------------------------------------------
+async function deployWithCommand(req, profile) {
+    const cwd = req.projectPath;
+    const command = (profile.command || '').trim();
+    if (!isRunnableCommand(command)) {
+        return { ok: false, actions: [], healed: [], errorKind: 'no_command', wrongMethod: true, errorDetail: 'No deploy command is known for this project.' };
+    }
+    const first = command.split(/\s+/)[0];
+    // Only a plain relative script path is checked up front; `~/x.sh`, absolute paths and `VAR=a ./x.sh` go to the shell as written
+    const looksLikeFile = /^\.{1,2}\//.test(first);
+    let line = command;
+    if (looksLikeFile) {
+        const abs = path.resolve(cwd, first);
+        if (!fs.existsSync(abs)) {
+            return { ok: false, actions: [], healed: [], errorKind: 'script_missing', wrongMethod: true, errorDetail: `The deploy script \`${first}\` does not exist in this project.` };
+        }
+        let executable = true;
+        try {
+            fs.accessSync(abs, fs.constants.X_OK);
+        }
+        catch {
+            executable = false;
+        }
+        if (!executable && /\.sh$/.test(first))
+            line = `bash ${command}`;
+    }
+    const healed = [];
+    // A deploy command may have half-finished before it failed: it is never re-run without a human saying so.
+    const res = await execShell(line, { cwd, timeoutMs: 15 * 60 * 1000 });
+    if (!res.ok) {
+        const cls = classifyFailure(res.tail);
+        return {
+            ok: false,
+            actions: [],
+            healed,
+            errorKind: cls.kind === 'unknown' ? 'deploy_command_failed' : cls.kind,
+            errorDetail: `Deploy command \`${command}\` ${res.timedOut ? 'timed out' : `exited with code ${res.code}`}: ${res.tail}`,
+        };
+    }
+    return { ok: true, actions: [`deployed with \`${command}\` (exit 0)`], healed };
+}
+async function httpStatus(url, timeoutMs) {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), timeoutMs);
+        const res = await fetch(url, { method: 'GET', redirect: 'follow', signal: ctrl.signal });
+        clearTimeout(t);
+        return res.status;
+    }
+    catch {
+        return 0;
+    }
+}
+async function smokeCheck(url, attempts) {
+    let status = 0;
+    for (let i = 0; i < attempts; i++) {
+        status = await httpStatus(url, 15000);
+        if (status > 0 && status < 400)
+            return status;
+        if (i < attempts - 1)
+            await sleep(8000);
+    }
+    return status;
+}
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+async function runMethod(req, profile, git, changedFiles) {
+    switch (profile.method) {
+        case 'github_actions':
+            if (!git.pushed && !profile.dispatchOnly) {
+                return { ok: false, actions: [], healed: [], errorKind: 'not_pushed', wrongMethod: true, errorDetail: 'GitHub Actions deploys from a pushed commit, but this project has no Git remote to push to.' };
+            }
+            return verifyGithubActions(req, profile, git, changedFiles);
+        case 'docker_compose':
+            return deployDockerCompose(req, profile, changedFiles);
+        case 'deploy_script':
+        case 'cloud_cli':
+            return deployWithCommand(req, profile);
+        case 'git_push':
+            return { ok: true, unverified: true, actions: git.pushed ? ['no deploy step is known for this project beyond pushing'] : ['nothing to push'], healed: [] };
+        case 'manual':
+            return { ok: true, unverified: true, actions: ['deployment is manual for this project — a human still needs to release it'], healed: [] };
+        default:
+            return { ok: true, unverified: true, actions: ['no deployment step is configured for this project'], healed: [] };
+    }
+}
+const HINTS = {
+    ci_failed: 'Open the workflow run above, fix the failing step, and reply "retry" — or tell me the correct route with `deploy: <method or command>`.',
+    container_unhealthy: 'Check the container logs above. Once it starts cleanly, reply "retry".',
+    docker_build_failed: 'The image did not build. Fix the build error above and reply "retry".',
+    commit_hook: 'A Git commit hook rejected the change. Fix what the hook reports (or tell me how to proceed) and reply "retry".',
+    deploy_command_failed: 'Fix the error above and reply "retry", or give me the right command with `deploy: <command>`.',
+};
+function profileFromCandidate(profile, candidate) {
+    return {
+        ...profile,
+        method: candidate.method,
+        command: candidate.command,
+        compose: candidate.compose,
+        dispatchOnly: Boolean(candidate.dispatchOnly),
+        source: 'detected',
+        evidence: candidate.evidence,
+    };
+}
+export async function runDeployment(req) {
+    const startedAt = Date.now();
+    await ensureUserPath();
+    const memory = loadMemory(req.projectPath);
+    let profile = resolveDeployProfile(req.projectPath, { bound: req.bound, memory });
+    if (req.override?.method) {
+        const humanCommand = (req.override.command || '').trim() || null;
+        const match = profile.method === req.override.method ? profile : null;
+        const alt = profile.alternatives.find((a) => a.method === req.override?.method);
+        profile = {
+            ...(match || (alt ? profileFromCandidate(profile, alt) : profile)),
+            method: req.override.method,
+            // A command the human typed is used exactly as written — never swapped for a detected one
+            command: humanCommand || match?.command || alt?.command || null,
+            source: 'explicit',
+            confidence: 'high',
+            needsConfirmation: false,
+            evidence: ['route confirmed on this card', ...((match || alt)?.evidence || [])],
+        };
+        if (humanCommand)
+            profile.compose = undefined;
+    }
+    const changedFiles = committablePaths(req.projectPath, req.files || []);
+    const pushPolicy = profile.method === 'github_actions' || profile.method === 'git_push'
+        ? 'required'
+        : profile.method === 'manual' || profile.method === 'none'
+            ? 'none'
+            : 'attempt';
+    const result = (partial, git) => ({
+        ok: false,
+        pending: false,
+        unverified: false,
+        method: profile.method,
+        command: profile.command,
+        commitHash: (git?.fullSha || '').slice(0, 7),
+        fullSha: git?.fullSha || '',
+        branch: git?.branch || '',
+        deployedNote: '',
+        errorDetail: '',
+        errorKind: null,
+        hint: '',
+        actions: [],
+        healed: [],
+        profile,
+        ...partial,
+    });
+    // First-time, unconfirmed routes with production reach: ask once (before touching Git), then remember the answer.
+    if (profile.needsConfirmation && !req.override) {
+        log.info('deploy.needs_confirmation', { card: req.cardId, project: req.projectPath, method: profile.method, command: profile.command });
+        return result({
+            errorKind: 'needs_confirmation',
+            errorDetail: `This project looks like it deploys with ${methodLabel(profile.method)}${profile.command ? ` (\`${profile.command}\`)` : ''}, but I have never run that here and nobody has confirmed it.`,
+        });
+    }
+    const git = await commitAndPush(req, profile, pushPolicy);
+    if (!git.ok) {
+        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);
+    }
+    let step = await runMethod(req, profile, git, changedFiles);
+    const healed = [...git.healed, ...step.healed];
+    // The chosen route does not apply here: fall back to the next-best one rather than giving up.
+    if (!step.ok && step.wrongMethod && !req.override && profile.source !== 'explicit' && profile.source !== 'user') {
+        // Only fall back to a routine route. One that needs a human's confirmation is never run as a "fallback".
+        const fallback = profile.alternatives.find((a) => a.score >= 55 && a.method !== profile.method && !requiresConfirmation(a));
+        if (fallback) {
+            recordAttempt(req.projectPath, { card_id: req.cardId, method: profile.method, command: profile.command, ok: false, kind: step.errorKind, error: step.errorDetail, wrong_method: true });
+            const previous = profile.method;
+            profile = profileFromCandidate(profile, fallback);
+            const retry = await runMethod(req, profile, git, changedFiles);
+            if (retry.ok) {
+                healed.push(`\`${previous}\` does not apply to this project (${(step.errorDetail || '').slice(0, 120)}); used ${methodLabel(profile.method)} instead and will remember that`);
+            }
+            step = { ...retry, healed: [...step.healed, ...retry.healed] };
+        }
+    }
+    if (!step.ok) {
+        const kind = step.errorKind || 'unknown';
+        recordAttempt(req.projectPath, {
+            card_id: req.cardId,
+            method: profile.method,
+            command: profile.command,
+            ok: false,
+            kind,
+            error: step.errorDetail,
+            commit: git.fullSha.slice(0, 7),
+            duration_ms: Date.now() - startedAt,
+            wrong_method: Boolean(step.wrongMethod),
+        });
+        log.warn('deploy.failed', { card: req.cardId, project: req.projectPath, method: profile.method, kind, error: step.errorDetail });
+        return result({
+            errorDetail: step.errorDetail || 'Deployment failed',
+            errorKind: kind,
+            hint: HINTS[kind] || classifyFailure(step.errorDetail || '').hint,
+            actions: [...git.actions, ...step.actions],
+            healed,
+        }, git);
+    }
+    const actions = [...git.actions, ...step.actions];
+    // Smoke check: a human-provided URL must respond; a guessed URL is only ever good news.
+    if (profile.liveUrl && /^https?:\/\//i.test(profile.liveUrl) && !step.pending && profile.method !== 'manual' && profile.method !== 'none') {
+        const trusted = profile.liveUrlSource === 'explicit' || profile.liveUrlSource === 'user';
+        const status = await smokeCheck(profile.liveUrl, trusted ? 4 : 1);
+        if (status > 0 && status < 400) {
+            actions.push(`verified live at ${profile.liveUrl} (HTTP ${status})`);
+        }
+        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);
+        }
+    }
+    // A human-pinned route is its own proof of intent; anything else only becomes "what worked" once verified
+    const unverified = Boolean(step.unverified);
+    recordAttempt(req.projectPath, {
+        card_id: req.cardId,
+        method: profile.method,
+        // The generated compose command is not stored: the stack is rediscovered each time (-p/-f can change,
+        // and only then can changed files be mapped to the services that need a rebuild or restart)
+        command: profile.method === 'docker_compose' && profile.compose ? null : profile.command,
+        ok: true,
+        pending: Boolean(step.pending),
+        unverified,
+        commit: git.fullSha.slice(0, 7),
+        duration_ms: Date.now() - startedAt,
+        live_url: profile.liveUrlSource === 'guessed' ? null : profile.liveUrl,
+    });
+    // Only claim "Deployed" when a deployment actually ran and was checked
+    const headline = step.pending
+        ? '⏳ **Deploying**'
+        : !unverified
+            ? '🚀 **Deployed**'
+            : git.pushed
+                ? '📤 **Pushed** (deployment not verified)'
+                : '📦 **Changes saved**';
+    const healedNote = healed.length > 0 ? `\n🩹 Self-healed: ${healed.join('; ')}.` : '';
+    const deployedNote = `${headline}: ${actions.join(', ') || `commit \`${git.fullSha.slice(0, 7)}\``}.${healedNote}`;
+    log.info('deploy.ok', { card: req.cardId, project: req.projectPath, method: profile.method, pending: Boolean(step.pending), ms: Date.now() - startedAt });
+    return result({
+        ok: true,
+        pending: Boolean(step.pending),
+        unverified,
+        deployedNote,
+        actions,
+        healed,
+        pendingVerification: step.pending
+            ? {
+                card_id: req.cardId,
+                card_title: req.title,
+                provider: '',
+                sha: git.fullSha,
+                branch: git.branch,
+                workflow_names: step.workflowNames || [],
+                started_at: new Date().toISOString(),
+                run_url: step.runUrl || null,
+            }
+            : undefined,
+    }, git);
+}
+/** Plain-English failure message for the card, including how to answer so the next attempt can succeed. */
+export function describeFailureForHuman(res) {
+    if (res.errorKind === 'needs_confirmation') {
+        const suggestion = res.command || res.method;
+        const others = res.profile.alternatives.filter((a) => a.score >= 25).slice(0, 3);
+        return [
+            `${res.errorDetail} Why I think so: ${res.profile.evidence[0] || 'it was the best match in the project'}.`,
+            '',
+            `Reply \`deploy: ${suggestion}\` to confirm — I will run it now and use it for every future card without asking again.`,
+            `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');
+    }
+    const lines = [`What failed: ${res.errorDetail.slice(0, 900)}`];
+    if (res.hint)
+        lines.push('', res.hint);
+    lines.push('', `I tried: ${methodLabel(res.method)}${res.command ? ` (\`${res.command}\`)` : ''} — chosen because ${res.profile.evidence[0] || 'it was the best match I found'}.`);
+    const alts = res.profile.alternatives.filter((a) => a.score >= 25).slice(0, 3);
+    if (alts.length > 0) {
+        lines.push(`Other routes I found: ${alts.map((a) => `\`${a.method}\`${a.command ? ` (\`${a.command}\`)` : ''}`).join(', ')}.`);
+    }
+    lines.push('', 'Reply **retry** once it is fixed, or tell me how this project deploys and I will remember it for every future card:', '`deploy: github_actions` · `deploy: docker_compose` · `deploy: manual` · or a command, e.g. `deploy: ./deploy/deploy.sh`');
+    return lines.join('\n');
+}