@agent-native/core 0.49.21 → 0.49.23

package/dist/cli/recap.js

@@ -14,13 +14,12 @@
  *   collect-diff  Collect the bounded base...head diff (excluding lockfiles,
  *                 build output, snapshots), cap it at ~600KB, and classify the
  *                 huge/tiny flags.
- *   mcp-config    Write the plan MCP client config for the chosen backend
- *                 (Claude Code JSON or Codex config.toml).
- *   mcp-smoke     Verify the configured Plan MCP endpoint exposes the publish
- *                 tools before spending runner time on Claude/Codex.
  *   scan          Refuse to hand a secret-leaking diff to the agent.
+ *   block-reference
+ *                 Fetch the live get-plan-blocks reference for the target app.
  *   build-prompt  Assemble the agent prompt = latest visual-recap skill bundle
  *                 + a task wrapper (or repo-pinned skill with --skill-source).
+ *   publish       Publish the agent-authored recap-source.json over HTTP.
  *   shot          Screenshot the published plan and upload it to the plan app's
  *                 signed public image route (for an inline PR-comment image).
  *   usage         Parse and emit agent token-usage/cost from stdout.
@@ -36,7 +35,6 @@
  */
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { readPlanPublishAuth } from "./plan-publish-store.js";
 import { PR_VISUAL_RECAP_WORKFLOW_YML } from "./pr-visual-recap-workflow.js";
@@ -196,12 +194,6 @@ export function writePrVisualRecapReusableCallerWorkflow(baseDir, options = {})
     return { status: "written", path: rel, existed: false };
 }
 const DEFAULT_RECAP_APP_URL = "https://plan.agent-native.com";
-const RECAP_MCP_CLIENT_HEADER = "agent-native-pr-visual-recap";
-export const RECAP_MCP_REQUIRED_TOOLS = [
-    "get-plan-blocks",
-    "create-visual-recap",
-    "set-resource-visibility",
-];
 export function normalizeRecapAgent(value) {
     const agent = (value || "claude").toLowerCase();
     if (agent === "codex")
@@ -1109,371 +1101,6 @@ function runCollectDiff(args) {
     process.stdout.write(`${JSON.stringify({ bytes, changed, huge, tiny })}\n`);
 }
 /* -------------------------------------------------------------------------- */
-/* MCP config writers — were the two `node -e` one-liners in the agent steps   */
-/* -------------------------------------------------------------------------- */
-/**
- * The Claude Code MCP config the recap agent loads: a single HTTP `plan` server
- * pointing at the app's `/_agent-native/mcp` endpoint, authorized with the
- * PLAN_RECAP_TOKEN. Pure (returns the JSON string) so it can be unit-tested.
- */
-export function buildRecapClaudeMcpConfig(appUrl, token) {
-    const url = appUrl.replace(/\/$/, "") + "/_agent-native/mcp";
-    return JSON.stringify({
-        mcpServers: {
-            plan: {
-                type: "http",
-                url,
-                headers: {
-                    Authorization: "Bearer " + token,
-                    "X-Agent-Native-MCP-Client": RECAP_MCP_CLIENT_HEADER,
-                    "X-Agent-Native-MCP-Full-Catalog": "1",
-                },
-            },
-            "agent-native-plans": {
-                type: "http",
-                url,
-                headers: {
-                    Authorization: "Bearer " + token,
-                    "X-Agent-Native-MCP-Client": RECAP_MCP_CLIENT_HEADER,
-                    "X-Agent-Native-MCP-Full-Catalog": "1",
-                },
-            },
-        },
-    });
-}
-/**
- * The Codex `config.toml` the recap agent loads. JSON.stringify the URL value so
- * a stray quote/newline in the app URL can't break out of the TOML basic string
- * (TOML shares JSON's escaping); the key and env-var name stay literal. Pure so
- * it can be unit-tested.
- */
-export function buildRecapCodexMcpConfig(appUrl) {
-    const url = appUrl.replace(/\/$/, "") + "/_agent-native/mcp";
-    return ("[mcp_servers.plan]\n" +
-        "url = " +
-        JSON.stringify(url) +
-        "\n" +
-        'bearer_token_env_var = "PLAN_RECAP_TOKEN"\n' +
-        'http_headers = { "X-Agent-Native-MCP-Client" = "agent-native-pr-visual-recap", "X-Agent-Native-MCP-Full-Catalog" = "1" }\n');
-}
-/**
- * Per-attempt timeout for the non-mutating MCP smoke probe. Short enough that
- * the workflow's 3-attempt retry loop can recover from a cold-start hang within
- * the job budget, long enough not to flake on a warm-but-slow response. The
- * plan app is serverless and intermittently 404s / stalls during a cold start
- * or mid-deploy; without a bound, undici's multi-minute default header/body
- * timeout would burn the whole job on a single stuck attempt.
- */
-const RECAP_MCP_SMOKE_TIMEOUT_MS = 15_000;
-function recapMcpUrl(appUrl) {
-    return appUrl.replace(/\/$/, "") + "/_agent-native/mcp";
-}
-function recapMcpSmokeHeaders(token) {
-    return {
-        authorization: `Bearer ${token}`,
-        accept: "application/json, text/event-stream",
-        "content-type": "application/json",
-        "mcp-protocol-version": "2025-06-18",
-        "x-agent-native-mcp-client": RECAP_MCP_CLIENT_HEADER,
-        "x-agent-native-mcp-full-catalog": "1",
-    };
-}
-function parseSseJsonPayload(raw) {
-    const dataLines = raw
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter((line) => line.startsWith("data:"))
-        .map((line) => line.slice("data:".length).trim())
-        .filter((line) => line && line !== "[DONE]");
-    for (let i = dataLines.length - 1; i >= 0; i -= 1) {
-        try {
-            return JSON.parse(dataLines[i]);
-        }
-        catch {
-            // Keep looking for a parseable event payload.
-        }
-    }
-    return null;
-}
-function parseMcpJsonPayload(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return null;
-    try {
-        return JSON.parse(trimmed);
-    }
-    catch {
-        return parseSseJsonPayload(trimmed);
-    }
-}
-function mcpRpcErrorMessage(payload) {
-    if (!payload || typeof payload !== "object")
-        return null;
-    const error = payload.error;
-    if (!error || typeof error !== "object")
-        return null;
-    const message = error.message;
-    return typeof message === "string" && message.trim()
-        ? message.trim()
-        : JSON.stringify(error);
-}
-async function postRecapMcpRpc(input) {
-    const response = await input.fetchFn(input.mcpUrl, {
-        method: "POST",
-        headers: recapMcpSmokeHeaders(input.token),
-        body: JSON.stringify({
-            jsonrpc: "2.0",
-            id: input.id,
-            method: input.method,
-            params: input.params ?? {},
-        }),
-        // Bound each attempt so a cold-start hang fails fast and the workflow's
-        // smoke retry loop can re-probe a (by-then warm) endpoint, instead of
-        // blocking on undici's multi-minute default timeout.
-        signal: AbortSignal.timeout(RECAP_MCP_SMOKE_TIMEOUT_MS),
-    });
-    const raw = await response.text().catch((err) => String(err));
-    if (!response.ok) {
-        const detail = sanitizeAgentFailureSummary(raw, 300);
-        return {
-            ok: false,
-            status: response.status,
-            raw,
-            reason: `Plan MCP ${input.method} returned HTTP ${response.status}${detail ? `: ${detail}` : ""}`,
-        };
-    }
-    const payload = parseMcpJsonPayload(raw);
-    if (!payload) {
-        return {
-            ok: false,
-            raw,
-            reason: `Plan MCP ${input.method} returned an unreadable response`,
-        };
-    }
-    const rpcError = mcpRpcErrorMessage(payload);
-    if (rpcError) {
-        return {
-            ok: false,
-            raw,
-            reason: `Plan MCP ${input.method} failed: ${sanitizeAgentFailureSummary(rpcError, 300)}`,
-        };
-    }
-    return { ok: true, payload };
-}
-function extractMcpToolNames(payload) {
-    const result = payload && typeof payload === "object"
-        ? payload.result
-        : undefined;
-    const tools = result && typeof result === "object"
-        ? result.tools
-        : undefined;
-    if (!Array.isArray(tools))
-        return [];
-    return tools
-        .map((tool) => tool && typeof tool === "object"
-        ? tool.name
-        : undefined)
-        .filter((name) => typeof name === "string" && !!name)
-        .sort();
-}
-function recapMcpSmokeFailure(input) {
-    const tools = input.tools ?? [];
-    const reason = sanitizeAgentFailureSummary(input.reason, 500);
-    return {
-        ok: false,
-        appUrl: input.appUrl,
-        mcpUrl: input.mcpUrl,
-        toolCount: tools.length,
-        tools,
-        requiredTools: [...input.requiredTools],
-        reason,
-        summary: `Plan MCP smoke check failed: ${reason}`,
-    };
-}
-/**
- * Non-mutating live contract check for PR Visual Recap publishing.
- *
- * The previous workflow discovered a broken Plan MCP catalog only after the
- * agent tried to publish and failed to create `recap-url.txt`. This probes the
- * same authenticated MCP endpoint first and requires the three tools that the
- * visual-recap skill needs to publish a hosted recap.
- */
-export async function smokeRecapMcpTools(input) {
-    const appUrl = input.appUrl ?? DEFAULT_RECAP_APP_URL;
-    const mcpUrl = recapMcpUrl(appUrl);
-    const requiredTools = input.requiredTools ?? RECAP_MCP_REQUIRED_TOOLS;
-    const token = input.token?.trim();
-    if (!token) {
-        return recapMcpSmokeFailure({
-            appUrl,
-            mcpUrl,
-            requiredTools,
-            reason: "PLAN_RECAP_TOKEN is empty",
-        });
-    }
-    const fetchFn = input.fetchFn ?? fetch;
-    try {
-        const init = await postRecapMcpRpc({
-            fetchFn,
-            mcpUrl,
-            token,
-            method: "initialize",
-            id: 1,
-            params: {
-                protocolVersion: "2025-06-18",
-                capabilities: {},
-                clientInfo: {
-                    name: RECAP_MCP_CLIENT_HEADER,
-                    version: "1.0.0",
-                },
-            },
-        });
-        if (!init.ok) {
-            return recapMcpSmokeFailure({
-                appUrl,
-                mcpUrl,
-                requiredTools,
-                reason: init.reason,
-            });
-        }
-        const listed = await postRecapMcpRpc({
-            fetchFn,
-            mcpUrl,
-            token,
-            method: "tools/list",
-            id: 2,
-        });
-        if (!listed.ok) {
-            return recapMcpSmokeFailure({
-                appUrl,
-                mcpUrl,
-                requiredTools,
-                reason: listed.reason,
-            });
-        }
-        const tools = extractMcpToolNames(listed.payload);
-        const missing = requiredTools.filter((name) => !tools.includes(name));
-        if (missing.length > 0) {
-            return recapMcpSmokeFailure({
-                appUrl,
-                mcpUrl,
-                tools,
-                requiredTools,
-                reason: `Plan MCP tools/list returned ${tools.length} tools but is missing required publishing tools: ${missing.join(", ")}`,
-            });
-        }
-        return {
-            ok: true,
-            appUrl,
-            mcpUrl,
-            toolCount: tools.length,
-            tools,
-            requiredTools: [...requiredTools],
-            summary: `Plan MCP smoke check passed: tools/list exposes ${requiredTools.join(", ")}.`,
-        };
-    }
-    catch (err) {
-        return recapMcpSmokeFailure({
-            appUrl,
-            mcpUrl,
-            requiredTools,
-            reason: `Plan MCP smoke check could not reach ${mcpUrl}: ${String(err)}`,
-        });
-    }
-}
-async function runMcpSmoke(args) {
-    const appUrl = optionalArg(args, "app-url") ??
-        process.env.PLAN_RECAP_APP_URL ??
-        DEFAULT_RECAP_APP_URL;
-    const token = optionalArg(args, "token") ?? process.env.PLAN_RECAP_TOKEN;
-    const result = await smokeRecapMcpTools({ appUrl, token });
-    writeGitHubOutput("ok", result.ok ? "true" : "false");
-    writeGitHubOutput("summary", result.summary);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    if (!result.ok)
-        process.exitCode = 1;
-}
-/**
- * `recap mcp-config` — write the plan MCP client config for the chosen backend,
- * replacing the two `node -e '...'` one-liners that previously lived inline in
- * the agent steps. PLAN_RECAP_TOKEN is read from the environment (claude only),
- * exactly as before.
- */
-function runMcpConfig(args) {
-    const agent = stringArg(args, "agent").toLowerCase();
-    const appUrl = stringArg(args, "app-url");
-    const force = Boolean(args["force"]);
-    if (agent === "claude") {
-        const token = process.env.PLAN_RECAP_TOKEN;
-        if (!token) {
-            process.stderr.write(`recap mcp-config: PLAN_RECAP_TOKEN is not set.\n` +
-                `Set it in the workflow environment before running this step.\n`);
-            process.exit(1);
-        }
-        const out = stringArg(args, "out");
-        fs.writeFileSync(path.resolve(out), buildRecapClaudeMcpConfig(appUrl, token));
-        process.stdout.write(`${JSON.stringify({ ok: true, agent, out })}\n`);
-        return;
-    }
-    if (agent === "codex") {
-        const out = optionalArg(args, "out") ??
-            path.join(os.homedir(), ".codex", "config.toml");
-        const absOut = path.resolve(out);
-        fs.mkdirSync(path.dirname(absOut), { recursive: true });
-        const newEntry = buildRecapCodexMcpConfig(appUrl);
-        const SECTION_MARKER = "[mcp_servers.plan]";
-        // If the file already exists and is non-empty, merge rather than overwrite.
-        let existing = "";
-        try {
-            const raw = fs.readFileSync(absOut, "utf8");
-            if (raw.trim())
-                existing = raw;
-        }
-        catch {
-            /* file absent — write fresh */
-        }
-        if (existing) {
-            if (existing.includes(SECTION_MARKER)) {
-                // Section already present — skip unless --force was passed.
-                if (!force) {
-                    process.stdout.write(`${JSON.stringify({ ok: true, agent, out, skipped: true, reason: "plan entry already present; pass --force to overwrite" })}\n`);
-                    return;
-                }
-                // --force: replace the existing [mcp_servers.plan] block.
-                // Remove lines from the section header until the next `[` header or EOF.
-                const lines = existing.split("\n");
-                const startIdx = lines.findIndex((l) => l.trim() === SECTION_MARKER);
-                let endIdx = lines.length;
-                for (let i = startIdx + 1; i < lines.length; i++) {
-                    if (lines[i].trimStart().startsWith("[")) {
-                        endIdx = i;
-                        break;
-                    }
-                }
-                const without = [
-                    ...lines.slice(0, startIdx),
-                    ...lines.slice(endIdx),
-                ].join("\n");
-                const merged = (without.trimEnd() ? without.trimEnd() + "\n\n" : "") + newEntry;
-                fs.writeFileSync(absOut, merged, { mode: 0o600 });
-            }
-            else {
-                // Append the new section to the existing config.
-                const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-                fs.writeFileSync(absOut, existing + separator + newEntry, {
-                    mode: 0o600,
-                });
-            }
-        }
-        else {
-            fs.writeFileSync(absOut, newEntry);
-        }
-        process.stdout.write(`${JSON.stringify({ ok: true, agent, out })}\n`);
-        return;
-    }
-    throw new Error(`Unknown --agent "${agent}" (expected "claude" or "codex")`);
-}
-/* -------------------------------------------------------------------------- */
 /* Prompt builder — repo SKILL.md + task wrapper                              */
 /* -------------------------------------------------------------------------- */
 /**
@@ -1591,6 +1218,9 @@ export function buildRecapPrompt(input) {
     }
     if (input.statPath)
         lines.push(`- Diff stat: \`${input.statPath}\` (read this file)`);
+    if (!input.localFiles) {
+        lines.push(`- Live plan block reference: \`${input.blockReferencePath ?? "recap-blocks.md"}\` (read this before authoring; it is the workflow-fetched \`get-plan-blocks\` output for the target Plan app).`);
+    }
     if (input.huge) {
         lines.push(`- The diff is LARGE — produce a **summarized** recap (top files + schema/API deltas), not an exhaustive one. The diff was truncated at the size cap — \`${input.statPath ?? "recap.stat"}\` contains the complete file list with per-file stats; for any file missing from \`${input.diffPath}\`, fetch it directly with \`git diff <base>...<head> -- <path>\`.`);
     }
@@ -1603,21 +1233,18 @@ export function buildRecapPrompt(input) {
         lines.push("3. Write the returned `url` from that command to `recap-url.txt` at the repo root, containing exactly one line. This file is the workflow's only hand-off.");
     }
     else {
-        lines.push("## Publish (this is the only way to produce output)");
-        lines.push(`The \`plan\` MCP server is configured for you, with \`agent-native-plans\` as a legacy alias. Call its tools by name (your host may expose them as \`get-plan-blocks\` / \`create-visual-recap\`, \`mcp__plan__get-plan-blocks\` / \`mcp__plan__create-visual-recap\`, or \`mcp__agent-native-plans__get-plan-blocks\` / \`mcp__agent-native-plans__create-visual-recap\` — same tools).`);
-        lines.push("This is a one-shot GitHub Actions run. Do not wait, sleep, back off, schedule wakeups, reminders, follow-ups, or retries in another turn. Either publish the recap and write `recap-url.txt` in this process, or report the MCP/tool failure plainly.");
-        lines.push("First call `get-plan-blocks`, then call `create-visual-recap`. If `create-visual-recap` is available but `get-plan-blocks` is not, the Plan MCP is connected but the block-registry tool is not visible to this runner. Report that the runner must expose `get-plan-blocks` through the workflow/tool allowlist or compact MCP catalog; do not describe that case as a disconnected Plan MCP.");
-        lines.push(`1. Call the **create-visual-recap** tool on the \`plan\` MCP server with grounded MDX derived ONLY from the real diff, passing \`visibility: "org"\` so the recap is published org-scoped (never public) server-side${input.prevPlanId
-            ? `, and also passing \`planId: "${input.prevPlanId}"\` so this REPLACES the existing recap plan`
-            : ""}${prSourceUrl
-            ? `, and also passing \`sourceUrl: "${prSourceUrl}"\` so the hosted recap page can link back to the PR`
-            : ""}.`);
-        lines.push("If `create-visual-recap` returns validation feedback about empty or invalid wireframes, make one immediate correction pass in this same process: revise the named WireframeBlock/Artboard MDX so each frame has real visible product text/controls, then call `create-visual-recap` again. Do not write `recap-url.txt` until the tool succeeds.");
-        lines.push(`2. Write the plan URL to a file named \`recap-url.txt\` at the repo root, containing exactly one line: \`${appUrl}/recaps/<the returned plan id>\`. This file is the workflow's only hand-off — do not print anything else as the deliverable.`);
-        lines.push(`3. (Fallback only — skip if step 1 succeeded) If \`create-visual-recap\` does not accept a \`visibility\` parameter (older server), call the **set-resource-visibility** tool with \`{ resourceType: "plan", resourceId: <the returned plan id>, visibility: "org" }\` after publishing.`);
+        lines.push("## Author Source (this is the only way to produce output)");
+        lines.push(`The workflow has already fetched the live \`get-plan-blocks\` output into \`${input.blockReferencePath ?? "recap-blocks.md"}\`. Read that file and treat it as the authoritative block/tag/schema reference for this run.`);
+        lines.push("Do NOT call the Plan MCP server and do NOT try to publish the recap yourself. CI publishes deterministically after you write the source file, which avoids host MCP registration flake.");
+        lines.push("This is a one-shot GitHub Actions run. Do not wait, sleep, back off, schedule wakeups, reminders, follow-ups, or retries in another turn. Either write `recap-source.json` in this process, or report why source authoring failed plainly.");
+        lines.push("1. Author grounded MDX recap source derived ONLY from the real diff. The final file must be valid JSON, not Markdown, not prose, and not a tool-call transcript.");
+        lines.push('2. Write a file named `recap-source.json` at the repo root with exactly this shape: `{ "title": string, "brief": string, "mdx": { "plan.mdx": string, "canvas.mdx"?: string, "prototype.mdx"?: string, ".plan-state.json"?: string, "assets/"?: { [filename: string]: string } } }`.');
+        lines.push("3. Do not write `recap-url.txt`; the deterministic CLI publisher writes that after it successfully POSTs your source to `create-visual-recap`.");
     }
     lines.push("");
-    lines.push("Do not invent file names, schema fields, or endpoints. Redact anything that looks like a secret. If the diff has no reviewable substance, still publish a minimal recap and write recap-url.txt. (CI already gated tiny diffs before invoking you — ignore the skill's advice to skip small diffs; always publish.)");
+    lines.push(input.localFiles
+        ? "Do not invent file names, schema fields, or endpoints. Redact anything that looks like a secret. If the diff has no reviewable substance, still create a minimal local recap and write recap-url.txt from the local preview command. (CI already gated tiny diffs before invoking you — ignore the skill's advice to skip small diffs; always produce output.)"
+        : "Do not invent file names, schema fields, or endpoints. Redact anything that looks like a secret. If the diff has no reviewable substance, still write a minimal `recap-source.json`. (CI already gated tiny diffs before invoking you — ignore the skill's advice to skip small diffs; always produce output.)");
     lines.push("");
     lines.push("## Depth preflight");
     lines.push("Before authoring the recap, read the diff/stat and make a quick surface/state inventory of changed files, routes/actions, rendered UI surfaces, popovers/dialogs, role/access states, empty/error states, and shared abstractions. The published recap must cover each meaningful item with a structured block or intentionally omit it because it is tiny, redundant, or not user-visible.");
@@ -1625,7 +1252,9 @@ export function buildRecapPrompt(input) {
     lines.push("");
     lines.push("---");
     lines.push("");
-    lines.push("# visual-recap skill (follow this exactly)");
+    lines.push("# visual-recap skill — use for recap CONTENT and structure");
+    lines.push("");
+    lines.push("Follow the skill below for WHAT makes a good recap: which blocks to use, grounding, house style, and review depth. IGNORE its publishing and hand-off instructions — in this run you have NO Plan MCP tools and must NOT publish the recap yourself. Publishing is handled exactly as described above (write the source file; CI publishes it deterministically).");
     lines.push("");
     lines.push(input.skillMd.trim());
     lines.push("");
@@ -1664,6 +1293,20 @@ async function githubRequest(token, apiPath, init = {}, fetchFn = fetch) {
         return undefined;
     return (await res.json());
 }
+export async function isPullRequestHeadCurrent(input) {
+    const expected = input.headSha.trim();
+    if (!expected)
+        return null;
+    const fn = input.fetchFn ?? fetch;
+    try {
+        const pr = await githubRequest(input.token, `/repos/${encodeURIComponent(input.owner)}/${encodeURIComponent(input.repo)}/pulls/${encodeURIComponent(input.issue)}`, {}, fn);
+        const current = pr.head?.sha?.trim();
+        return current ? current === expected : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function findExistingComment(input) {
     const fn = input.fetchFn ?? fetch;
     for (let page = 1;; page += 1) {
@@ -1738,6 +1381,10 @@ function trustedRecapImageUrl(raw, base) {
 /** Build the sticky comment body from the workflow's environment. */
 export function buildCommentBody(env = process.env) {
     const lines = [MARKER];
+    const headSha = (env.HEAD_SHA || "").trim();
+    const headMarker = /^[a-f0-9]{7,64}$/i.test(headSha)
+        ? `<!-- head-sha: ${headSha} -->`
+        : "";
     // Last-known plan id threaded from the previous run (supplied via PREV_PLAN_ID
     // when the comment is rebuilt from scratch, or parsed from the env on upsert).
     // We always emit the plan-id marker when any plan id is known so that a
@@ -1760,6 +1407,8 @@ export function buildCommentBody(env = process.env) {
         lines.push(`Reason: \`${reason}\`.`);
         if (prevPlanId)
             lines.push("", `<!-- plan-id: ${prevPlanId} -->`);
+        if (headMarker)
+            lines.push("", headMarker);
         return lines.join("\n");
     }
     // Tiny diffs aren't worth a recap. The workflow upserts this state as a sticky
@@ -1771,6 +1420,8 @@ export function buildCommentBody(env = process.env) {
         lines.push("The change in this pull request is too small to be worth a visual recap. This is informational only and does **not** block the PR.");
         if (prevPlanId)
             lines.push("", `<!-- plan-id: ${prevPlanId} -->`);
+        if (headMarker)
+            lines.push("", headMarker);
         return lines.join("\n");
     }
     const planUrl = (env.PLAN_URL || "").trim();
@@ -1813,6 +1464,8 @@ export function buildCommentBody(env = process.env) {
         }
         if (markerPlanId)
             lines.push("", `<!-- plan-id: ${markerPlanId} -->`);
+        if (headMarker)
+            lines.push("", headMarker);
         return lines.join("\n");
     }
     // Image URLs are produced by our own recap-image route, but validate each is
@@ -1840,6 +1493,8 @@ export function buildCommentBody(env = process.env) {
         lines.push("> Large diff — this recap is a **summarized** view (top files + schema/API deltas).");
     }
     lines.push("", `<!-- plan-id: ${planId} -->`);
+    if (headMarker)
+        lines.push("", headMarker);
     return lines.join("\n");
 }
 /* -------------------------------------------------------------------------- */
@@ -1898,6 +1553,7 @@ function runBuildPrompt(args) {
         appUrl: optionalArg(args, "app-url") ?? "https://plan.agent-native.com",
         diffPath,
         statPath: optionalArg(args, "stat"),
+        blockReferencePath: optionalArg(args, "block-reference"),
         prevPlanId: optionalArg(args, "prev-plan-id"),
         huge: args.huge === true || args.huge === "true",
         localFiles: args["local-files"] === true || args["local-files"] === "true",
@@ -1910,6 +1566,278 @@ function runBuildPrompt(args) {
     fs.writeFileSync(path.resolve(out), prompt);
     process.stdout.write(`${JSON.stringify({ ok: true, out, skillSource: skill.source, bytes: prompt.length })}\n`);
 }
+const RECAP_SOURCE_FILENAME = "recap-source.json";
+const RECAP_URL_REASON_FILENAME = "recap-url-reason.txt";
+const RECAP_HTTP_TIMEOUT_MS = 45_000;
+function writeRecapUrlReason(reason, cwd = process.cwd()) {
+    fs.writeFileSync(path.join(cwd, RECAP_URL_REASON_FILENAME), `${sanitizeAgentFailureSummary(reason, 1000)}\n`);
+}
+function readRecapUrlReason(cwd = process.cwd()) {
+    return readTextIfExists(path.join(cwd, RECAP_URL_REASON_FILENAME));
+}
+function validateRecapSourcePayload(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${RECAP_SOURCE_FILENAME} must contain a JSON object.`);
+    }
+    const obj = value;
+    if (obj.title !== undefined && typeof obj.title !== "string") {
+        throw new Error(`${RECAP_SOURCE_FILENAME} title must be a string.`);
+    }
+    if (obj.brief !== undefined && typeof obj.brief !== "string") {
+        throw new Error(`${RECAP_SOURCE_FILENAME} brief must be a string.`);
+    }
+    if (!obj.mdx || typeof obj.mdx !== "object" || Array.isArray(obj.mdx)) {
+        throw new Error(`${RECAP_SOURCE_FILENAME} must include an mdx object.`);
+    }
+    const mdx = obj.mdx;
+    if (typeof mdx["plan.mdx"] !== "string" || !mdx["plan.mdx"].trim()) {
+        throw new Error(`${RECAP_SOURCE_FILENAME} mdx["plan.mdx"] must be a non-empty string.`);
+    }
+    for (const key of ["canvas.mdx", "prototype.mdx", ".plan-state.json"]) {
+        if (mdx[key] !== undefined && typeof mdx[key] !== "string") {
+            throw new Error(`${RECAP_SOURCE_FILENAME} mdx["${key}"] must be a string when present.`);
+        }
+    }
+    const assets = mdx["assets/"];
+    if (assets !== undefined) {
+        if (!assets || typeof assets !== "object" || Array.isArray(assets)) {
+            throw new Error(`${RECAP_SOURCE_FILENAME} mdx["assets/"] must be an object when present.`);
+        }
+        for (const [name, body] of Object.entries(assets)) {
+            if (typeof body !== "string") {
+                throw new Error(`${RECAP_SOURCE_FILENAME} asset ${JSON.stringify(name)} must be a string.`);
+            }
+        }
+    }
+    return {
+        ...(typeof obj.title === "string" ? { title: obj.title } : {}),
+        ...(typeof obj.brief === "string" ? { brief: obj.brief } : {}),
+        mdx,
+    };
+}
+export function readRecapSourcePayload(filePath = RECAP_SOURCE_FILENAME) {
+    const abs = path.resolve(filePath);
+    let text;
+    try {
+        text = fs.readFileSync(abs, "utf8");
+    }
+    catch (err) {
+        throw new Error(`${RECAP_SOURCE_FILENAME} was not created by the agent (${String(err)}).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${RECAP_SOURCE_FILENAME} was not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return validateRecapSourcePayload(parsed);
+}
+function recapActionEndpoint(appUrl, action) {
+    return `${appUrl.replace(/\/$/, "")}/_agent-native/actions/${action}`;
+}
+async function fetchJsonWithTimeout(url, init, fetchFn) {
+    return await fetchFn(url, {
+        ...init,
+        signal: init.signal ?? AbortSignal.timeout(RECAP_HTTP_TIMEOUT_MS),
+    });
+}
+export async function fetchRecapBlockReference(input) {
+    const fetchFn = input.fetchFn ?? fetch;
+    const out = input.out ?? "recap-blocks.md";
+    const endpoint = new URL(recapActionEndpoint(input.appUrl, "get-plan-blocks"));
+    endpoint.searchParams.set("format", "reference");
+    const response = await fetchJsonWithTimeout(endpoint.toString(), { method: "GET", headers: { accept: "application/json" } }, fetchFn);
+    if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`get-plan-blocks failed ${response.status} ${response.statusText}: ${sanitizeAgentFailureSummary(detail, 500)}`);
+    }
+    const json = (await response.json().catch(() => null));
+    if (!json?.reference) {
+        throw new Error("get-plan-blocks returned no reference text.");
+    }
+    fs.writeFileSync(path.resolve(out), json.reference);
+    return { ok: true, out, count: json.count };
+}
+function recapUrlFromPublishResult(result, appUrl) {
+    const candidates = [];
+    const ids = [];
+    const visit = (value, depth = 0) => {
+        if (!value || typeof value !== "object" || depth > 3)
+            return;
+        const obj = value;
+        for (const key of ["webUrl", "url", "path", "href"]) {
+            const candidate = obj[key];
+            if (typeof candidate === "string")
+                candidates.push(candidate);
+        }
+        for (const key of ["planId", "id"]) {
+            const candidate = obj[key];
+            if (typeof candidate === "string" &&
+                /^[A-Za-z0-9_-]{1,80}$/.test(candidate)) {
+                ids.push(candidate);
+            }
+        }
+        for (const key of ["plan", "openLink", "link", "result"]) {
+            visit(obj[key], depth + 1);
+        }
+    };
+    visit(result);
+    for (const candidate of candidates) {
+        const canonical = canonicalRecapUrl(candidate, appUrl);
+        if (canonical)
+            return canonical;
+    }
+    for (const id of ids) {
+        const canonical = canonicalRecapUrl(`/recaps/${id}`, appUrl);
+        if (canonical)
+            return canonical;
+    }
+    return "";
+}
+function shouldRetryRecapPublish(status) {
+    return (status === 408 ||
+        status === 409 ||
+        status === 425 ||
+        status === 429 ||
+        status >= 500);
+}
+export async function publishRecapSource(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const sourcePath = input.sourcePath ?? path.join(cwd, RECAP_SOURCE_FILENAME);
+    const out = input.out ?? path.join(cwd, "recap-url.txt");
+    const token = input.token.trim();
+    if (!token)
+        throw new Error("PLAN_RECAP_TOKEN is empty.");
+    const source = readRecapSourcePayload(sourcePath);
+    const sourceUrl = input.sourceUrl ??
+        (input.repo && input.pr
+            ? `https://github.com/${input.repo}/pull/${input.pr}`
+            : undefined);
+    const body = {
+        ...(input.prevPlanId ? { planId: input.prevPlanId } : {}),
+        ...(source.title ? { title: source.title } : {}),
+        ...(source.brief ? { brief: source.brief } : {}),
+        visibility: "org",
+        source: "imported",
+        ...(input.repo ? { repoPath: input.repo } : {}),
+        ...(sourceUrl ? { sourceUrl } : {}),
+        currentFocus: "visual recap review",
+        status: "review",
+        mdx: source.mdx,
+    };
+    const endpoint = recapActionEndpoint(input.appUrl, "create-visual-recap");
+    const fetchFn = input.fetchFn ?? fetch;
+    let lastError = "";
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+        try {
+            const response = await fetchJsonWithTimeout(endpoint, {
+                method: "POST",
+                headers: {
+                    accept: "application/json",
+                    "content-type": "application/json",
+                    authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(body),
+            }, fetchFn);
+            const text = await response.text().catch((err) => String(err));
+            if (!response.ok) {
+                lastError = `create-visual-recap failed ${response.status} ${response.statusText}: ${sanitizeAgentFailureSummary(text, 800)}`;
+                if (attempt < 3 && shouldRetryRecapPublish(response.status)) {
+                    await delay(attempt * 2000);
+                    continue;
+                }
+                throw new Error(lastError);
+            }
+            let result = null;
+            try {
+                result = text ? JSON.parse(text) : null;
+            }
+            catch {
+                throw new Error("create-visual-recap returned non-JSON output.");
+            }
+            const url = recapUrlFromPublishResult(result, input.appUrl);
+            if (!url) {
+                throw new Error("create-visual-recap succeeded but did not return a usable /recaps/<id> URL or plan id.");
+            }
+            fs.writeFileSync(path.resolve(out), `${url}\n`);
+            try {
+                fs.rmSync(path.join(cwd, RECAP_URL_REASON_FILENAME), { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+            return { ok: true, url, out };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+            if (attempt < 3 &&
+                /fetch failed|network|timeout|timed out|ECONNRESET|ETIMEDOUT/i.test(lastError)) {
+                await delay(attempt * 2000);
+                continue;
+            }
+            throw new Error(lastError);
+        }
+    }
+    throw new Error(lastError || "create-visual-recap failed.");
+}
+async function runBlockReference(args) {
+    const appUrl = optionalArg(args, "app-url") ??
+        process.env.PLAN_RECAP_APP_URL ??
+        DEFAULT_RECAP_APP_URL;
+    const out = optionalArg(args, "out") ?? "recap-blocks.md";
+    try {
+        const result = await fetchRecapBlockReference({ appUrl, out });
+        writeGitHubOutput("ok", "true");
+        writeGitHubOutput("out", result.out);
+        writeGitHubOutput("reason", "");
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    catch (err) {
+        const reason = sanitizeAgentFailureSummary(err instanceof Error ? err.message : String(err), 1000);
+        writeRecapUrlReason(reason);
+        writeGitHubOutput("ok", "false");
+        writeGitHubOutput("out", "");
+        writeGitHubOutput("reason", reason);
+        process.stdout.write(`${JSON.stringify({ ok: false, reason })}\n`);
+        process.exitCode = 1;
+    }
+}
+async function runPublish(args) {
+    const appUrl = optionalArg(args, "app-url") ??
+        process.env.PLAN_RECAP_APP_URL ??
+        DEFAULT_RECAP_APP_URL;
+    const token = optionalArg(args, "token") ?? process.env.PLAN_RECAP_TOKEN ?? "";
+    const out = optionalArg(args, "out") ?? "recap-url.txt";
+    const done = (obj) => {
+        process.stdout.write(`${JSON.stringify(obj)}\n`);
+    };
+    try {
+        const result = await publishRecapSource({
+            appUrl,
+            token,
+            sourcePath: optionalArg(args, "source") ?? RECAP_SOURCE_FILENAME,
+            out,
+            prevPlanId: optionalArg(args, "prev-plan-id"),
+            repo: optionalArg(args, "repo") ?? process.env.GITHUB_REPOSITORY,
+            pr: optionalArg(args, "pr") ?? process.env.PR_NUMBER,
+            sourceUrl: optionalArg(args, "source-url"),
+        });
+        writeGitHubOutput("ok", "true");
+        writeGitHubOutput("plan_url", result.url);
+        writeGitHubOutput("reason", "");
+        done(result);
+    }
+    catch (err) {
+        const reason = sanitizeAgentFailureSummary(err instanceof Error ? err.message : String(err), 1000);
+        writeRecapUrlReason(reason);
+        writeGitHubOutput("ok", "false");
+        writeGitHubOutput("plan_url", "");
+        writeGitHubOutput("reason", reason);
+        done({ ok: false, reason });
+        process.exitCode = 1;
+    }
+}
 function delay(ms) {
     return ms > 0
         ? new Promise((resolve) => setTimeout(resolve, ms))
@@ -2012,6 +1940,47 @@ async function defaultImportPlaywright() {
         return (await import("@playwright/test"));
     }
 }
+const RECAP_SYSTEM_CHROME_EXECUTABLES = [
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/chromium",
+];
+function shouldTrySystemChromeFallback(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /Executable doesn't exist|playwright install|browser.*not found|chromium.*not found/i.test(message);
+}
+export async function launchRecapChromium(chromium) {
+    const launchOptions = { args: ["--no-sandbox"] };
+    try {
+        return await chromium.launch(launchOptions);
+    }
+    catch (err) {
+        if (!shouldTrySystemChromeFallback(err))
+            throw err;
+        const fallbackErrors = [];
+        for (const executablePath of RECAP_SYSTEM_CHROME_EXECUTABLES) {
+            if (!fs.existsSync(executablePath))
+                continue;
+            try {
+                process.stderr.write(`[recap shot] Playwright browser unavailable; trying system Chrome at ${executablePath}\n`);
+                return await chromium.launch({ ...launchOptions, executablePath });
+            }
+            catch (fallbackErr) {
+                const message = fallbackErr instanceof Error
+                    ? fallbackErr.message
+                    : String(fallbackErr);
+                fallbackErrors.push(`${executablePath}: ${message}`);
+                process.stderr.write(`[recap shot] system Chrome launch failed at ${executablePath}: ${message}\n`);
+            }
+        }
+        if (fallbackErrors.length) {
+            const originalMessage = err instanceof Error ? err.message : String(err);
+            throw new Error(`${originalMessage}; system Chrome fallback failed (${fallbackErrors.join("; ")})`, { cause: err });
+        }
+        throw err;
+    }
+}
 function parseRecapScreenshotTheme(value) {
     if (value === undefined)
         return undefined;
@@ -2080,13 +2049,14 @@ importPlaywright = defaultImportPlaywright) {
         return;
     }
     let captured = false;
+    let reason = "";
     let browser;
     const hardTimer = setTimeout(() => {
         done({ ok: false, reason: "hard 60s timeout reached" });
         process.exit(0);
     }, 60_000);
     try {
-        browser = await chromium.launch({ args: ["--no-sandbox"] });
+        browser = await launchRecapChromium(chromium);
         const context = await browser.newContext({
             viewport: RECAP_SHOT_VIEWPORT,
             deviceScaleFactor: RECAP_SHOT_DEVICE_SCALE_FACTOR,
@@ -2211,12 +2181,20 @@ importPlaywright = defaultImportPlaywright) {
         });
         await page.waitForTimeout(250);
         await page.screenshot({ path: out });
-        // If the captured PNG is over the upload cap, remove it so the upload step
-        // sees no file and the comment falls back to a link-only recap.
+        // If the captured PNG is over the upload cap, retry at CSS-pixel scale
+        // before giving up. The server route rejects oversized files, and the
+        // GitHub comment can only embed an image after a successful upload.
         const firstSize = fs.existsSync(out) ? fs.statSync(out).size : 0;
         if (firstSize > RECAP_SHOT_MAX_BYTES) {
-            process.stderr.write(`[recap shot] PNG is ${firstSize} bytes (cap ${RECAP_SHOT_MAX_BYTES}) — skipping upload\n`);
+            process.stderr.write(`[recap shot] PNG is ${firstSize} bytes (cap ${RECAP_SHOT_MAX_BYTES}) — retrying at CSS-pixel scale\n`);
             fs.unlinkSync(out);
+            await page.screenshot({ path: out, scale: "css" });
+            const retrySize = fs.existsSync(out) ? fs.statSync(out).size : 0;
+            if (retrySize > RECAP_SHOT_MAX_BYTES) {
+                reason = `screenshot PNG exceeded upload cap (${retrySize} bytes > ${RECAP_SHOT_MAX_BYTES})`;
+                process.stderr.write(`[recap shot] ${reason}; skipping upload\n`);
+                fs.unlinkSync(out);
+            }
         }
         captured = fs.existsSync(out);
         await browser.close();
@@ -2240,8 +2218,12 @@ importPlaywright = defaultImportPlaywright) {
     let imageUrl = null;
     if (captured && token && appUrl) {
         imageUrl = await uploadRecapImage({ appUrl, token, pngPath: out });
+        if (!imageUrl) {
+            reason = "screenshot captured but image upload failed";
+        }
     }
-    done({ ok: captured, out, imageUrl });
+    const ok = captured && (!(token && appUrl) || !!imageUrl);
+    done({ ok, out, imageUrl, ...(reason ? { reason } : {}) });
 }
 async function runComment(args, sub) {
     const token = stringArg(args, "token");
@@ -2259,6 +2241,24 @@ async function runComment(args, sub) {
         return;
     }
     if (sub === "upsert") {
+        const headSha = optionalArg(args, "head-sha") ?? process.env.HEAD_SHA ?? "";
+        if (headSha) {
+            const current = await isPullRequestHeadCurrent({
+                token,
+                owner,
+                repo,
+                issue,
+                headSha,
+            });
+            if (current === false) {
+                process.stdout.write(`${JSON.stringify({
+                    action: "skipped",
+                    id: 0,
+                    reason: "stale head sha",
+                })}\n`);
+                return;
+            }
+        }
         const result = await upsertComment({
             token,
             owner,
@@ -2617,13 +2617,16 @@ export function canonicalRecapUrl(rawUrl, appUrl) {
     }
 }
 export function inferLocalRecapUrlFailureReason(input = {}) {
-    const recapUrlPath = path.join(input.cwd ?? process.cwd(), "recap-url.txt");
+    const cwd = input.cwd ?? process.cwd();
+    const explicitReason = readRecapUrlReason(cwd);
+    const recapUrlPath = path.join(cwd, "recap-url.txt");
     const raw = readTextIfExists(recapUrlPath);
-    if (raw === null)
-        return "recap-url.txt was not created by the agent.";
+    if (raw === null) {
+        return explicitReason?.trim() || "recap-url.txt was not created.";
+    }
     const value = raw.replace(/[\r\n\s]/g, "");
     if (!value)
-        return "recap-url.txt was empty.";
+        return explicitReason?.trim() || "recap-url.txt was empty.";
     const appUrl = input.appUrl ||
         process.env.PLAN_RECAP_APP_URL ||
         "https://plan.agent-native.com";
@@ -2637,10 +2640,12 @@ export function inferLocalRecapUrlFailureReason(input = {}) {
         if (parsed.origin !== trusted.origin) {
             return `recap-url.txt points at ${parsed.origin}, expected ${trusted.origin}.`;
         }
-        return "recap-url.txt did not contain a valid /plans/<id> or /recaps/<id> URL for the configured plan app.";
+        return (explicitReason?.trim() ||
+            "recap-url.txt did not contain a valid /plans/<id> or /recaps/<id> URL for the configured plan app.");
     }
     catch {
-        return "recap-url.txt was not a valid URL or recap path.";
+        return (explicitReason?.trim() ||
+            "recap-url.txt was not a valid URL or recap path.");
     }
 }
 export function buildRecapFailureDiagnostic(input) {
@@ -3063,10 +3068,10 @@ Usage:
   npx @agent-native/core@latest recap setup [--repo owner/name] [--agent claude|codex] [--app-url <url>] [--skip-secrets] [--dry-run] [--force]
   npx @agent-native/core@latest recap doctor [--repo owner/name] [--agent claude|codex] [--app-url <url>]
   npx @agent-native/core@latest recap collect-diff --base <baseSha> --head <headSha> [--out recap.diff] [--stat recap.stat]
-  npx @agent-native/core@latest recap mcp-config --agent claude|codex --app-url <url> [--out <path>]
-  npx @agent-native/core@latest recap mcp-smoke [--app-url <url>] [--token <planToken>]
+  npx @agent-native/core@latest recap block-reference [--app-url <url>] [--out recap-blocks.md]
   npx @agent-native/core@latest recap scan --diff <path> [--mode off|high-confidence|strict]
-  npx @agent-native/core@latest recap build-prompt --pr <n> [--repo owner/name] [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--prev-plan-id <id>] [--huge] [--local-files] [--local-dir <folder>] [--skill-source auto|latest|repo] [--out <path>]
+  npx @agent-native/core@latest recap build-prompt --pr <n> [--repo owner/name] [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--block-reference recap-blocks.md] [--prev-plan-id <id>] [--huge] [--local-files] [--local-dir <folder>] [--skill-source auto|latest|repo] [--out <path>]
+  npx @agent-native/core@latest recap publish [--source recap-source.json] [--out recap-url.txt] [--repo owner/name] [--pr <n>] [--prev-plan-id <id>] [--app-url <url>] [--token <planToken>]
   npx @agent-native/core@latest recap shot --url <planUrl> [--token <planToken>] [--app-url <url>] [--out recap.png] [--theme light|dark]
   npx @agent-native/core@latest recap usage --plan-url <planUrl> --result-file <path> --app-url <url> --token <planToken> [--agent claude|codex] [--model <id>]
   npx @agent-native/core@latest recap agent-summary --result-file <path> [--stderr-file <path>] [--exit-code-file <path>] [--agent claude|codex]
@@ -3103,11 +3108,12 @@ Usage:
     shapes such as private key blocks and known provider token prefixes. Set
     VISUAL_RECAP_SECRET_SCAN=strict, or pass --mode strict, to restore generic
     TOKEN/SECRET assignment suppression; set off to disable this preflight.
-  npx @agent-native/core@latest recap mcp-smoke
-    Non-mutating Plan MCP JSON-RPC smoke test. Calls initialize + tools/list
-    against PLAN_RECAP_APP_URL / PLAN_RECAP_TOKEN and requires get-plan-blocks,
-    create-visual-recap, and set-resource-visibility to be exposed. Writes
-    ok=<true|false> and summary=<diagnostic> to $GITHUB_OUTPUT.
+  npx @agent-native/core@latest recap block-reference
+    Fetch the target Plan app's live get-plan-blocks reference over the public
+    action route and write it to recap-blocks.md for the CI agent to read.
+  npx @agent-native/core@latest recap publish
+    Validate recap-source.json from the CI agent, publish it by POSTing the
+    authenticated create-visual-recap action, and write recap-url.txt.
   npx @agent-native/core@latest recap setup
     Write/refresh .github/workflows/pr-visual-recap.yml, then configure GitHub
     Actions secrets and variables with gh when values are available from env or
@@ -3130,11 +3136,8 @@ export async function runRecap(argv) {
         case "collect-diff":
             runCollectDiff(args);
             return;
-        case "mcp-config":
-            runMcpConfig(args);
-            return;
-        case "mcp-smoke":
-            await runMcpSmoke(args);
+        case "block-reference":
+            await runBlockReference(args);
             return;
         case "scan":
             runScan(args);
@@ -3142,6 +3145,9 @@ export async function runRecap(argv) {
         case "build-prompt":
             runBuildPrompt(args);
             return;
+        case "publish":
+            await runPublish(args);
+            return;
         case "shot":
             await runShot(args);
             return;