@topline-build/harness-mcp 0.2.0 → 0.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, lstat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, realpath, lstat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import os from "node:os";
 import path from "node:path";
@@ -10,14 +10,29 @@ import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
-const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
+export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
-const SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.2.0";
-const DEFAULT_OAUTH_SCOPES = ["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy"];
+export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
+export const HARNESS_MCP_VERSION = "0.5.0";
+export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
+export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
+    { flag: "--url", env: "TOPLINE_API_URL", aliases: ["PLATFORM_API_URL", "OVERSITE_API_URL"], required: true, description: "Topline tenant base URL. HTTPS is required except for loopback development." },
+    { flag: "--workspace-root", env: "TOPLINE_WORKSPACE_ROOT", aliases: ["PLATFORM_WORKSPACE_ROOT"], default: "current working directory", description: "Local root that contains artifact app directories." },
+    { flag: "--surface", env: "TOPLINE_MCP_SURFACE", default: "build", allowed: ["build", "harness"], description: "Build is the current surface; harness preserves legacy OAuth compatibility." },
+    { flag: "--protocol-version", env: "TOPLINE_MCP_PROTOCOL_VERSION", aliases: ["PLATFORM_MCP_PROTOCOL_VERSION"], default: DEFAULT_MCP_PROTOCOL_VERSION, description: "MCP protocol version sent to Topline HTTP endpoints." },
+    { flag: "--auth-file", env: "TOPLINE_MCP_AUTH_FILE", aliases: ["PLATFORM_MCP_AUTH_FILE"], default: "per-tenant file in the local Topline config directory", description: "OAuth credential cache. Keep it outside artifact app directories." },
+    { flag: "--scopes", env: "TOPLINE_MCP_SCOPES", aliases: ["PLATFORM_MCP_SCOPES"], default: DEFAULT_OAUTH_SCOPES.join(" "), description: "Space- or comma-separated OAuth scopes." },
+    { flag: "--timeout-ms", env: "TOPLINE_MCP_TIMEOUT_MS", aliases: ["PLATFORM_MCP_TIMEOUT_MS", "OVERSITE_MCP_TIMEOUT_MS"], default: DEFAULT_TIMEOUT_MS, description: "Positive request timeout in milliseconds." },
+    { flag: "--token", env: "TOPLINE_MCP_TOKEN", aliases: ["PLATFORM_MCP_TOKEN", "OVERSITE_MCP_TOKEN"], description: "Advanced manual bearer-token fallback. Prefer browser-approved OAuth." }
+].map((option) => Object.freeze({
+    ...option,
+    ...(option.aliases ? { aliases: Object.freeze(option.aliases) } : {}),
+    ...(option.allowed ? { allowed: Object.freeze(option.allowed) } : {})
+})));
 const BLOCK_SIZE = 512;
 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
 const MAX_UNPACKED_BYTES = 512 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 512 * 1024;
 const MAX_FILES = 25_000;
 const MAX_DEPTH = 64;
 const FORBIDDEN_DIRS = new Set([".git", "node_modules", ".next", ".vite", ".turbo", ".cache", "dist", "build", "coverage"]);
@@ -55,7 +70,7 @@ export function parseHarnessOptions(argv, env = process.env) {
         surface: surfaceRaw,
         token,
         authFile,
-        oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : DEFAULT_OAUTH_SCOPES,
+        oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : [...DEFAULT_OAUTH_SCOPES],
         timeoutMs: Math.floor(timeoutMs),
         protocolVersion,
         workspaceRoot
@@ -80,30 +95,34 @@ export function cliInfo(argv) {
     return [
         "Usage: topline-mcp --url https://your-topline-host [--workspace-root <path>]",
         "",
-        "Environment:",
-        "  TOPLINE_API_URL           Required unless --url is passed",
-        "  TOPLINE_WORKSPACE_ROOT    Defaults to the current working directory",
-        "  TOPLINE_MCP_SURFACE       Defaults to build; harness keeps legacy OAuth compatibility",
-        "  TOPLINE_MCP_TOKEN         Optional manual token fallback",
-        "  TOPLINE_MCP_AUTH_FILE     Optional OAuth credential cache path",
-        "  TOPLINE_MCP_TIMEOUT_MS    Defaults to 120000",
+        "Options and environment:",
+        ...BUILD_MCP_SETUP_OPTIONS.map((option) => {
+            const requirement = option.required ? "required" : `default: ${option.default ?? "optional"}`;
+            return `  ${option.flag.padEnd(20)} ${option.env} (${requirement})`;
+        }),
         "",
         "Examples:",
         "  npx -y @topline-build/harness-mcp --url https://hawx.topline.build",
         "  TOPLINE_API_URL=https://hawx.topline.build npx -y @topline-build/harness-mcp"
     ].join("\n");
 }
-export function createHarnessMcpStdioServer(opts) {
-    const mcp = new McpServer({ name: SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
-    mcp.setRequestHandler(ListToolsRequestSchema, async () => listTools());
+export function createHarnessMcpStdioServer(opts, toolAllowlist) {
+    const allowedTools = toolAllowlist ? new Set(toolAllowlist) : null;
+    const listedTools = () => {
+        const listed = listTools();
+        return allowedTools ? { ...listed, tools: listed.tools.filter((tool) => allowedTools.has(tool.name)) } : listed;
+    };
+    const mcp = new McpServer({ name: BUILD_MCP_SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
+    mcp.setRequestHandler(ListToolsRequestSchema, async () => listedTools());
     mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
-        const reportsProgress = req.params.name === "platform_deploy_artifact_app";
-        if (reportsProgress)
-            await sendProgress(extra, 0, 1, "Starting artifact deployment");
+        if (allowedTools && !allowedTools.has(req.params.name)) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
+        }
+        const reportsProgress = req.params.name === "platform_deploy_artifact_app" || req.params.name === "platform_wait_artifact_deploy";
         try {
-            const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {});
-            if (reportsProgress)
-                await sendProgress(extra, 1, 1, "Completed artifact deployment");
+            const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, reportsProgress
+                ? { onProgress: (progress, message) => sendProgress(extra, progress, 1, message) }
+                : undefined);
             return result;
         }
         catch (err) {
@@ -111,15 +130,12 @@ export function createHarnessMcpStdioServer(opts) {
                 throw err;
             if (reportsProgress)
                 await sendProgress(extra, 1, 1, "Failed artifact deployment");
-            return {
-                content: [{ type: "text", text: redactSecrets(err instanceof Error ? err.message : String(err), opts) }],
-                isError: true
-            };
+            return structuredToolError(redactSecrets(err instanceof Error ? err.message : String(err), opts));
         }
     });
     return mcp;
 }
-export async function callHarnessTool(opts, name, args) {
+export async function callHarnessTool(opts, name, args, hooks) {
     const input = isRecord(args) ? args : {};
     const tool = listTools().tools.find((candidate) => candidate.name === name);
     if (!tool)
@@ -129,8 +145,21 @@ export async function callHarnessTool(opts, name, args) {
         return toolError(`Invalid arguments for ${name}: ${inputError}`);
     let result;
     switch (name) {
+        case "platform_connection_check":
+        case "platform_list_build_workspaces":
+        case "platform_list_artifact_drafts":
+        case "platform_deploy_operation":
+        case "platform_validate_artifact":
+        case "platform_run_artifact_smoke":
+        case "platform_plan_artifact_draft_delete":
+        case "platform_delete_artifact_draft":
+            result = toolResult(await callHostedBuildTool(opts, name, input));
+            break;
         case "platform_deploy_artifact_app":
-            result = toolResult(await deployArtifactApp(opts, input));
+            result = toolResult(await deployArtifactApp(opts, input, hooks?.onProgress));
+            break;
+        case "platform_inspect_artifact_app":
+            result = toolResult(await inspectArtifactApp(opts, input));
             break;
         case "platform_artifact_status":
             result = toolResult(await getArtifactStatus(opts, stringArg(input, "artifactId"), numberArg(input, "limit")));
@@ -144,6 +173,12 @@ export async function callHarnessTool(opts, name, args) {
         case "platform_storybook_access":
             result = toolResult(storybookAccess(opts));
             break;
+        case "platform_wait_artifact_deploy":
+            result = toolResult(await waitForArtifactDeploy(opts, input, hooks?.onProgress));
+            break;
+        case "platform_init_artifact_app":
+            result = toolResult(await initArtifactApp(opts, input));
+            break;
         default:
             throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
     }
@@ -152,12 +187,24 @@ export async function callHarnessTool(opts, name, args) {
         : null;
     return outputError ? toolError(`Invalid output for ${name}: ${outputError}`) : result;
 }
-export async function deployArtifactApp(opts, input) {
+export async function deployArtifactApp(opts, input, onProgress) {
+    await onProgress?.(0, "Reading artifact manifest");
     const appDir = stringArg(input, "appDir");
-    const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
-    const platformAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
+    const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
+    await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
+    const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
+    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const clientRequestId = optionalString(input, "requestId") ?? createHash("sha256")
+        .update(JSON.stringify({ apiUrl: platformBaseUrl(opts), appDir: platformAppDir, manifestId: manifest.id ?? null }))
+        .digest("hex");
+    await onProgress?.(0.2, "Packaging local artifact app");
     const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
+    const expectedBundleSha256 = optionalString(input, "expectedBundleSha256")?.toLowerCase();
+    if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
+        throw new Error("artifact_app_bundle_changed_after_inspection");
+    }
+    await onProgress?.(0.4, "Creating private artifact draft");
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
         headers: await jsonHeaders(opts),
@@ -166,6 +213,8 @@ export async function deployArtifactApp(opts, input) {
             title: optionalString(input, "title"),
             description: optionalString(input, "description"),
             projectId: optionalString(input, "projectId"),
+            clientRequestId,
+            bundleSha256: bundle.sha256,
             manifest
         })
     });
@@ -175,6 +224,7 @@ export async function deployArtifactApp(opts, input) {
     const artifactId = stringValue(createdRecord.artifactId, "artifactId");
     const artifactVersionId = stringValue(createdRecord.artifactVersionId, "artifactVersionId");
     const bearerToken = await getBearerToken(opts);
+    await onProgress?.(0.6, "Uploading bundle and waiting for trusted draft deployment");
     const deployed = await fetchJson(opts, `${artifactAppsPath(opts)}/${encodeURIComponent(artifactId)}/deploy-bundle`, {
         method: "POST",
         headers: {
@@ -186,11 +236,16 @@ export async function deployArtifactApp(opts, input) {
         },
         body: bundle.body
     });
+    await onProgress?.(1, "Completed trusted draft deployment");
+    const deployedRecord = asRecord(deployed);
+    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId : null;
     return {
         ok: true,
         artifactId,
         artifactVersionId,
         manifestId: typeof manifest.id === "string" ? manifest.id : null,
+        clientRequestId,
+        operationId,
         bundle: {
             fileCount: bundle.fileCount,
             byteCount: bundle.byteCount,
@@ -201,6 +256,132 @@ export async function deployArtifactApp(opts, input) {
         deploy: deployed
     };
 }
+export async function inspectArtifactApp(opts, input) {
+    const appDir = stringArg(input, "appDir");
+    const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
+    await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
+    const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
+    const manifest = await readManifest(absoluteAppDir);
+    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
+    return {
+        ok: true,
+        packageReady: true,
+        serverManifestValidationRequired: true,
+        appDir: workspaceAppDir,
+        platformAppDir,
+        manifest: {
+            id: typeof manifest.id === "string" ? manifest.id : null,
+            manifestVersion: typeof manifest.manifestVersion === "number" ? manifest.manifestVersion : null,
+            title: typeof manifest.title === "string" ? manifest.title : null,
+            kind: typeof manifest.kind === "string" ? manifest.kind : null
+        },
+        bundle: {
+            fileCount: bundle.fileCount,
+            byteCount: bundle.byteCount,
+            sha256: bundle.sha256,
+            excluded: bundle.excluded
+        },
+        nextAction: "Call platform_deploy_artifact_app with the same appDir and expectedBundleSha256 set to bundle.sha256 when this local package is ready to deploy."
+    };
+}
+async function callHostedBuildTool(opts, name, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error(`${name}_requires_build_surface`);
+    const headers = await jsonHeaders(opts);
+    const payload = asRecord(await fetchJson(opts, `${platformBaseUrl(opts)}/mcp/build`, {
+        method: "POST",
+        headers: { ...headers, accept: "application/json, text/event-stream" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: `stdio-${Date.now()}`,
+            method: "tools/call",
+            params: { name, arguments: input }
+        })
+    }));
+    if (payload.error) {
+        const error = asRecord(payload.error);
+        throw new Error(`platform_mcp_tool_error:${String(error.message ?? "unknown_error")}`);
+    }
+    const result = asRecord(payload.result);
+    if (result.isError === true) {
+        const content = Array.isArray(result.content) ? result.content.filter(isRecord) : [];
+        const message = content.find((item) => item.type === "text" && typeof item.text === "string")?.text;
+        throw new Error(`platform_mcp_tool_error:${String(message ?? "tool_failed")}`);
+    }
+    if (isRecord(result.structuredContent))
+        return result.structuredContent;
+    throw new Error(`platform_mcp_tool_output_missing:${name}`);
+}
+export async function waitForArtifactDeploy(opts, input, onProgress) {
+    const artifactId = stringArg(input, "artifactId");
+    const operationId = stringArg(input, "operationId");
+    const timeoutSeconds = Math.min(Math.max(numberArg(input, "timeoutSeconds") ?? 300, 1), 900);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let afterSeq = 0;
+    let latest = {};
+    while (Date.now() < deadline) {
+        latest = asRecord(await callHostedBuildTool(opts, "platform_deploy_operation", { artifactId, operationId, afterSeq }));
+        const progress = typeof latest.progress === "number" ? latest.progress : 0.7;
+        const events = Array.isArray(latest.events) ? latest.events.filter(isRecord) : [];
+        const eventMessage = [...events].reverse().find((event) => typeof event.message === "string")?.message;
+        await onProgress?.(progress, typeof eventMessage === "string" ? eventMessage : `Artifact deployment: ${String(latest.phase ?? latest.taskStatus ?? "running")}`);
+        if (typeof latest.nextSeq === "number")
+            afterSeq = latest.nextSeq;
+        if (latest.terminal === true) {
+            if (latest.successful !== true)
+                throw new Error(`artifact_deploy_failed:${String(latest.taskStatus ?? "failed")}`);
+            return latest;
+        }
+        const waitMs = typeof latest.nextPollAfterMs === "number" ? Math.min(Math.max(latest.nextPollAfterMs, 250), 10_000) : 2_000;
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    throw new Error(`artifact_deploy_wait_timeout:${operationId}`);
+}
+export async function initArtifactApp(opts, input) {
+    const appDir = stringArg(input, "appDir");
+    const title = optionalString(input, "title") ?? "Topline artifact";
+    const manifestId = (optionalString(input, "manifestId") ?? path.basename(appDir))
+        .toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!manifestId || manifestId.length > 80)
+        throw new Error("artifact_manifest_id_invalid");
+    const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
+    if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
+        throw new Error("artifact_app_scaffold_target_not_empty");
+    await mkdir(path.join(absoluteAppDir, "src"), { recursive: true });
+    const manifest = {
+        manifestVersion: 2,
+        id: manifestId,
+        title,
+        kind: "tool",
+        runtime: { target: "aws_lambda_function_url", region: "us-west-2", entryPoint: "artifactApp" },
+        build: { command: "node src/index.js --build", outputDir: "dist" },
+        validation: { localCommand: "node src/index.js --test", testCommand: "node src/index.js --test --artifact-tests-json" },
+        routes: [
+            { path: "/", kind: "page", handler: "artifactApp" },
+            { path: "/_artifact/health", kind: "api", handler: "artifactApp" }
+        ],
+        sourceBindings: [],
+        env: ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"],
+        viewerPolicy: "private"
+    };
+    const packageJson = { name: manifestId, private: true, type: "module", main: "src/index.js", scripts: { build: "node src/index.js --build", test: "node src/index.js --test" } };
+    const safeTitle = title.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    const source = `import { mkdirSync, writeFileSync } from "node:fs";\nimport path from "node:path";\n\nconst page = ${JSON.stringify(`<!doctype html><html><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Ready.</p></main></body></html>`)};\n\nexport function artifactApp(_req, res) {\n  res.setHeader("content-type", "text/html; charset=utf-8");\n  res.end(page);\n}\n\nif (process.argv.includes("--build")) {\n  mkdirSync("dist", { recursive: true });\n  writeFileSync(path.join("dist", "index.html"), page, "utf8");\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n  console.log(JSON.stringify({ tests: [{ description: "The artifact renders a visible app root.", required: true, status: "passed", summary: "The page includes data-platform-artifact-root.", evidence: { selector: "data-platform-artifact-root" } }] }));\n} else if (process.argv.includes("--build") || process.argv.includes("--test")) {\n  console.log("artifact app template ok");\n}\n`;
+    await Promise.all([
+        writeFile(path.join(absoluteAppDir, "artifact-app.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" }),
+        writeFile(path.join(absoluteAppDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`, { flag: "wx" }),
+        writeFile(path.join(absoluteAppDir, "src", "index.js"), source, { flag: "wx" })
+    ]);
+    return {
+        ok: true,
+        appDir: workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir),
+        manifestId,
+        title,
+        files: ["artifact-app.json", "package.json", "src/index.js"],
+        nextAction: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
+    };
+}
 export async function getArtifactStatus(opts, artifactId, limit) {
     const query = new URLSearchParams();
     if (limit)
@@ -289,6 +470,8 @@ export function storybookAccess(opts) {
 }
 export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
     const root = path.resolve(appDir);
+    if ((await lstat(root)).isSymbolicLink())
+        throw new Error("artifact_app_bundle_symlink_forbidden:.");
     const prefix = archivePrefix ? validateArchivePrefix(archivePrefix) : "";
     const files = [];
     const excluded = [];
@@ -297,11 +480,13 @@ export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
         throw new Error("artifact_app_bundle_empty");
     let byteCount = 0;
     const chunks = [];
-    for (const file of files.sort((a, b) => a.relative.localeCompare(b.relative))) {
-        byteCount += file.size;
-        if (byteCount > MAX_UNPACKED_BYTES)
+    for (const file of files.sort((a, b) => compareUtf8Paths(a.relative, b.relative))) {
+        if (byteCount + file.size > MAX_UNPACKED_BYTES)
             throw new Error(`artifact_app_bundle_unpacked_too_large:${MAX_UNPACKED_BYTES}`);
         const content = await readFile(file.absolute);
+        byteCount += content.length;
+        if (byteCount > MAX_UNPACKED_BYTES)
+            throw new Error(`artifact_app_bundle_unpacked_too_large:${MAX_UNPACKED_BYTES}`);
         chunks.push(tarHeader(prefix ? `${prefix}/${file.relative}` : file.relative, content.length));
         chunks.push(content);
         chunks.push(Buffer.alloc(padSize(content.length)));
@@ -315,9 +500,12 @@ export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
         fileCount: files.length,
         byteCount,
         sha256: createHash("sha256").update(body).digest("hex"),
-        excluded
+        excluded: excluded.sort(compareUtf8Paths)
     };
 }
+function compareUtf8Paths(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
 async function walk(root, current, files, excluded) {
     const entries = await readdir(current, { withFileTypes: true });
     for (const entry of entries) {
@@ -335,6 +523,8 @@ async function walk(root, current, files, excluded) {
             await walk(root, absolute, files, excluded);
         }
         else if (entry.isFile()) {
+            if (stat.nlink > 1)
+                throw new Error(`artifact_app_bundle_hardlink_forbidden:${relative}`);
             files.push({ absolute, relative, size: stat.size });
             if (files.length > MAX_FILES)
                 throw new Error(`artifact_app_bundle_file_limit:${MAX_FILES}`);
@@ -343,7 +533,32 @@ async function walk(root, current, files, excluded) {
 }
 async function readManifest(appDir) {
     const manifestPath = path.join(appDir, "artifact-app.json");
-    const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+    let stat;
+    try {
+        stat = await lstat(manifestPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error("artifact_app_manifest_not_found");
+        throw error;
+    }
+    if (stat.isSymbolicLink()) {
+        throw new Error("artifact_app_bundle_symlink_forbidden:artifact-app.json");
+    }
+    if (!stat.isFile())
+        throw new Error("artifact_app_manifest_must_be_file");
+    if (stat.size > MAX_MANIFEST_BYTES)
+        throw new Error(`artifact_app_manifest_too_large:${MAX_MANIFEST_BYTES}`);
+    const source = await readFile(manifestPath, "utf8");
+    if (Buffer.byteLength(source) > MAX_MANIFEST_BYTES)
+        throw new Error(`artifact_app_manifest_too_large:${MAX_MANIFEST_BYTES}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new Error("artifact_app_manifest_invalid_json");
+    }
     if (!isRecord(parsed))
         throw new Error("artifact_app_manifest_must_be_object");
     return parsed;
@@ -351,10 +566,61 @@ async function readManifest(appDir) {
 function resolveWorkspacePath(workspaceRoot, inputPath) {
     const resolved = path.resolve(workspaceRoot, inputPath);
     const relative = path.relative(workspaceRoot, resolved);
-    if (relative.startsWith("..") || path.isAbsolute(relative))
+    if (pathEscapesRoot(relative))
         throw new Error("appDir_must_be_inside_workspace_root");
     return resolved;
 }
+async function resolveWorkspacePathSafely(workspaceRoot, inputPath) {
+    const root = path.resolve(workspaceRoot);
+    const resolved = resolveWorkspacePath(root, inputPath);
+    const rootRealPath = await realpath(root);
+    let existingPath = root;
+    let candidatePath = root;
+    const relative = path.relative(root, resolved);
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        candidatePath = path.join(candidatePath, segment);
+        try {
+            const stat = await lstat(candidatePath);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`appDir_symlink_forbidden:${toPosix(path.relative(root, candidatePath))}`);
+            }
+            existingPath = candidatePath;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    const existingRealPath = await realpath(existingPath);
+    const realRelative = path.relative(rootRealPath, existingRealPath);
+    if (pathEscapesRoot(realRelative)) {
+        throw new Error("appDir_must_resolve_inside_workspace_root");
+    }
+    return resolved;
+}
+function pathEscapesRoot(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
+async function assertAuthFileOutsideAppDir(authFile, appDir) {
+    const relative = path.relative(path.resolve(appDir), path.resolve(authFile));
+    if (!pathEscapesRoot(relative))
+        throw new Error("artifact_app_auth_file_inside_app_dir");
+    let realAuthFile;
+    let realAppDir;
+    try {
+        realAuthFile = await realpath(authFile);
+        realAppDir = await realpath(appDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const realRelative = path.relative(realAppDir, realAuthFile);
+    if (!pathEscapesRoot(realRelative))
+        throw new Error("artifact_app_auth_file_inside_app_dir");
+}
 function workspaceRelativeAppDir(workspaceRoot, absoluteAppDir) {
     const relative = toPosix(path.relative(path.resolve(workspaceRoot), path.resolve(absoluteAppDir)));
     return relative ? validateArchivePrefix(relative) : ".";
@@ -392,7 +658,9 @@ function tarHeader(name, size) {
     writeOctal(header, 108, 8, 0);
     writeOctal(header, 116, 8, 0);
     writeOctal(header, 124, 12, size);
-    writeOctal(header, 136, 12, Math.floor(Date.now() / 1000));
+    // Content-identical retries must produce the same bundle hash. A wall-clock
+    // mtime would make every archive look new even when no source file changed.
+    writeOctal(header, 136, 12, 0);
     header.fill(0x20, 148, 156);
     header.write("0", 156, 1, "utf8");
     header.write("ustar", 257, 5, "utf8");
@@ -444,6 +712,10 @@ async function fetchJson(opts, url, init) {
             payload = { detail: text.slice(0, 500) };
         }
         if (!response.ok) {
+            const code = isRecord(payload) && typeof payload.error === "string" ? payload.error : null;
+            if (code === "artifact_source_git_app_dir_mismatch") {
+                throw new Error("artifact_source_git_app_dir_mismatch: Use the same local app/source root as the existing artifact, or deploy without artifactId to create a new draft.");
+            }
             throw new Error(`platform_harness_http_error:${response.status}:${redactSecrets(JSON.stringify(payload), opts)}`);
         }
         return payload;
@@ -457,127 +729,312 @@ async function fetchJson(opts, url, init) {
         clearTimeout(timeout);
     }
 }
-export function listTools() {
-    return {
-        tools: [
-            {
-                name: "platform_deploy_artifact_app",
-                description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
-                annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        appDir: { type: "string", minLength: 1 },
-                        artifactId: { type: "string" },
-                        title: { type: "string" },
-                        description: { type: "string" },
-                        projectId: { type: "string" }
-                    },
-                    required: ["appDir"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" },
-                        artifactId: { type: "string" },
-                        artifactVersionId: { type: "string" },
-                        bundle: { type: "object" },
-                        create: { type: "object" },
-                        deploy: { type: "object" }
-                    },
-                    required: ["ok", "artifactId", "artifactVersionId", "bundle", "create", "deploy"]
-                }
+const BUILD_MCP_TOOLS = [
+    {
+        name: "platform_connection_check",
+        description: "Complete the one-time Developer Access verification challenge for this Build MCP client.",
+        annotations: mcpToolAnnotations("platform_connection_check", { readOnly: false, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                verificationCode: { type: "string", minLength: 16, maxLength: 80 }
             },
-            {
-                name: "platform_artifact_status",
-                description: "Read private draft deployment status for a hosted artifact app.",
-                annotations: mcpToolAnnotations("platform_artifact_status", { readOnly: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: { artifactId: { type: "string", minLength: 1 }, limit: { type: "integer", minimum: 1, maximum: 50 } },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
-                        deployments: { type: "array", items: { type: "object" } }
-                    },
-                    required: ["ok", "phase", "artifactId", "deployments"]
-                }
+            required: ["verificationCode"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, verified: { type: "boolean" }, product: { type: "string", enum: ["build"] }, verifiedAt: { type: "string" }
             },
-            {
-                name: "platform_read_artifact_logs",
-                description: "Read bounded, redacted deployment logs for a hosted artifact app.",
-                annotations: mcpToolAnnotations("platform_read_artifact_logs", { readOnly: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        artifactId: { type: "string", minLength: 1 },
-                        deploymentRecordId: { type: "string" },
-                        environment: { type: "string", enum: ["draft", "live"] },
-                        limit: { type: "integer", minimum: 1, maximum: 200 },
-                        severity: { type: "string" },
-                        contains: { type: "string" },
-                        since: { type: "string", format: "date-time" },
-                        windowMinutes: { type: "integer", minimum: 1, maximum: 1440 },
-                        trace: { type: "string" },
-                        requestId: { type: "string" },
-                        route: { type: "string" }
-                    },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" },
-                        phase: { type: "string" },
-                        artifactId: { type: "string" },
-                        entries: { type: "array", items: { type: "object" } }
-                    },
-                    required: ["ok", "phase", "artifactId"]
-                }
+            required: ["ok", "verified", "product", "verifiedAt"]
+        }
+    },
+    {
+        name: "platform_init_artifact_app",
+        description: "Create a minimal, validated artifact app starter inside the configured local workspace.",
+        annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
+        inputSchema: {
+            type: "object",
+            properties: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
+            required: ["appDir"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: { ok: { type: "boolean" }, appDir: { type: "string" }, manifestId: { type: "string" }, title: { type: "string" }, files: { type: "array", items: { type: "string" } }, nextAction: { type: "string" } },
+            required: ["ok", "appDir", "manifestId", "title", "files", "nextAction"]
+        }
+    },
+    {
+        name: "platform_deploy_artifact_app",
+        description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
+        annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                appDir: { type: "string", minLength: 1 },
+                artifactId: { type: "string", format: "uuid" },
+                title: { type: "string" },
+                description: { type: "string" },
+                projectId: { type: "string", format: "uuid" },
+                expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed." },
+                requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
             },
-            {
-                name: "platform_open_artifact",
-                description: "Return the operator URL and latest draft/live URLs for a hosted artifact app.",
-                annotations: mcpToolAnnotations("platform_open_artifact", { readOnly: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: { artifactId: { type: "string", minLength: 1 } },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, artifactId: { type: "string" }, openUrl: { type: "string" },
-                        draftUrl: { type: ["string", "null"] }, liveUrl: { type: ["string", "null"] }, versionUrl: { type: ["string", "null"] }
-                    },
-                    required: ["ok", "artifactId", "openUrl", "draftUrl", "liveUrl", "versionUrl"]
-                }
+            required: ["appDir"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" },
+                artifactId: { type: "string" },
+                artifactVersionId: { type: "string" },
+                clientRequestId: { type: "string" },
+                operationId: { type: ["string", "null"] },
+                bundle: { type: "object" },
+                create: { type: "object" },
+                deploy: { type: "object" }
             },
-            {
-                name: "platform_storybook_access",
-                description: "Return the tenant Storybook preview URL and HTTP MCP server config.",
-                annotations: mcpToolAnnotations("platform_storybook_access", { readOnly: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {},
-                    additionalProperties: false
-                },
-                outputSchema: {
+            required: ["ok", "artifactId", "artifactVersionId", "clientRequestId", "operationId", "bundle", "create", "deploy"]
+        }
+    },
+    {
+        name: "platform_inspect_artifact_app",
+        description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.",
+        annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
+        inputSchema: {
+            type: "object",
+            properties: { appDir: { type: "string", minLength: 1 } },
+            required: ["appDir"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" },
+                packageReady: { type: "boolean" },
+                serverManifestValidationRequired: { type: "boolean" },
+                appDir: { type: "string" },
+                platformAppDir: { type: "string" },
+                manifest: { type: "object" },
+                bundle: { type: "object" },
+                nextAction: { type: "string" }
+            },
+            required: ["ok", "packageReady", "serverManifestValidationRequired", "appDir", "platformAppDir", "manifest", "bundle", "nextAction"]
+        }
+    },
+    {
+        name: "platform_list_build_workspaces",
+        description: "List Topline workspaces available for artifact placement.",
+        annotations: mcpToolAnnotations("platform_list_build_workspaces", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, workspaces: { type: "array", items: { type: "object" } } }, required: ["ok", "workspaces"] }
+    },
+    {
+        name: "platform_list_artifact_drafts",
+        description: "Discover private artifact drafts created through this Build MCP connection.",
+        annotations: mcpToolAnnotations("platform_list_artifact_drafts", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { projectId: { type: "string", format: "uuid" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, drafts: { type: "array", items: { type: "object" } } }, required: ["ok", "drafts"] }
+    },
+    {
+        name: "platform_deploy_operation",
+        description: "Read durable server-side progress for one artifact deployment operation.",
+        annotations: mcpToolAnnotations("platform_deploy_operation", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, operationId: { type: "string", format: "uuid" }, afterSeq: { type: "integer", minimum: 0 } }, required: ["artifactId", "operationId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+    },
+    {
+        name: "platform_wait_artifact_deploy",
+        description: "Wait for a durable deployment operation and stream server-derived progress.",
+        annotations: mcpToolAnnotations("platform_wait_artifact_deploy", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, operationId: { type: "string", format: "uuid" }, timeoutSeconds: { type: "integer", minimum: 1, maximum: 900 } }, required: ["artifactId", "operationId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+    },
+    {
+        name: "platform_artifact_status",
+        description: "Read private draft deployment status for a hosted artifact app.",
+        annotations: mcpToolAnnotations("platform_artifact_status", { readOnly: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: { artifactId: { type: "string", format: "uuid" }, limit: { type: "integer", minimum: 1, maximum: 50 } },
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
+                deployments: { type: "array", items: { type: "object" } }
+            },
+            required: ["ok", "phase", "artifactId", "deployments"]
+        }
+    },
+    {
+        name: "platform_read_artifact_logs",
+        description: "Read bounded, redacted deployment logs for a hosted artifact app.",
+        annotations: mcpToolAnnotations("platform_read_artifact_logs", { readOnly: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "string", format: "uuid" },
+                deploymentRecordId: { type: "string", format: "uuid" },
+                environment: { type: "string", enum: ["draft", "live"] },
+                limit: { type: "integer", minimum: 1, maximum: 200 },
+                severity: { type: "string" },
+                contains: { type: "string" },
+                since: { type: "string", format: "date-time" },
+                windowMinutes: { type: "integer", minimum: 1, maximum: 1440 },
+                trace: { type: "string" },
+                requestId: { type: "string" },
+                route: { type: "string" }
+            },
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" },
+                phase: { type: "string" },
+                artifactId: { type: "string" },
+                entries: { type: "array", items: { type: "object" } }
+            },
+            required: ["ok", "phase", "artifactId"]
+        }
+    },
+    {
+        name: "platform_open_artifact",
+        description: "Return the operator URL and latest draft/live URLs for a hosted artifact app.",
+        annotations: mcpToolAnnotations("platform_open_artifact", { readOnly: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: { artifactId: { type: "string", format: "uuid" } },
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, artifactId: { type: "string" }, openUrl: { type: "string" },
+                draftUrl: { type: ["string", "null"] }, liveUrl: { type: ["string", "null"] }, versionUrl: { type: ["string", "null"] }
+            },
+            required: ["ok", "artifactId", "openUrl", "draftUrl", "liveUrl", "versionUrl"]
+        }
+    },
+    {
+        name: "platform_storybook_access",
+        description: "Return the tenant Storybook preview URL and HTTP MCP server config.",
+        annotations: mcpToolAnnotations("platform_storybook_access", { readOnly: true }),
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, storybookUrl: { type: "string" }, mcpUrl: { type: "string" }, mcpServers: { type: "object" }
+            },
+            required: ["ok", "storybookUrl", "mcpUrl", "mcpServers"]
+        }
+    },
+    {
+        name: "platform_validate_artifact",
+        description: "Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.",
+        annotations: mcpToolAnnotations("platform_validate_artifact", { readOnly: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "string", format: "uuid" },
+                deploymentRecordId: { type: "string", format: "uuid" }
+            },
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
+                deploymentRecordId: { type: "string" }, deploymentState: { type: "string" },
+                healthy: { type: "boolean" }, checkedAt: { type: ["string", "null"] },
+                draftUrl: { type: ["string", "null"] }, smoke: { type: ["object", "null"] }
+            },
+            required: ["ok", "phase", "artifactId", "deploymentRecordId", "deploymentState", "healthy", "checkedAt", "draftUrl", "smoke"]
+        }
+    },
+    {
+        name: "platform_run_artifact_smoke",
+        description: "Rerun the trusted draft smoke check and return fresh rendered-page evidence.",
+        annotations: mcpToolAnnotations("platform_run_artifact_smoke", { readOnly: false, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, deploymentRecordId: { type: "string", format: "uuid" } }, required: ["artifactId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, deploymentRecordId: { type: "string" }, smoke: { type: "object" }, validation: { type: "object" } }, required: ["ok", "phase", "artifactId", "deploymentRecordId", "smoke", "validation"] }
+    },
+    {
+        name: "platform_plan_artifact_draft_delete",
+        description: "Preview cleanup effects and receive the state-bound plan token required for deletion.",
+        annotations: mcpToolAnnotations("platform_plan_artifact_draft_delete", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" } }, required: ["artifactId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, eligible: { type: "boolean" }, effects: { type: "object" }, planToken: { type: "string" } }, required: ["ok", "phase", "artifactId", "eligible", "effects", "planToken"] }
+    },
+    {
+        name: "platform_delete_artifact_draft",
+        description: "Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.",
+        annotations: mcpToolAnnotations("platform_delete_artifact_draft", { readOnly: false, destructive: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "string", format: "uuid" },
+                confirmArtifactId: { type: "string", format: "uuid" },
+                planToken: { type: "string", minLength: 1 }
+            },
+            required: ["artifactId", "confirmArtifactId", "planToken"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
+            required: ["ok", "deleted", "artifactId"]
+        }
+    }
+].map(withRecoveryOutputSchema);
+export function listTools() {
+    // Preserve the original tools/list isolation boundary: callers must not be
+    // able to mutate the registry used by later requests or input validation.
+    return { tools: structuredClone(BUILD_MCP_TOOLS) };
+}
+function withRecoveryOutputSchema(value) {
+    const tool = value;
+    if (!tool.outputSchema)
+        return tool;
+    return {
+        ...tool,
+        outputSchema: {
+            type: "object",
+            oneOf: [
+                tool.outputSchema,
+                {
                     type: "object",
                     properties: {
-                        ok: { type: "boolean" }, storybookUrl: { type: "string" }, mcpUrl: { type: "string" }, mcpServers: { type: "object" }
+                        ok: { const: false },
+                        error: {
+                            type: "object",
+                            properties: {
+                                code: { type: "string" },
+                                message: { type: "string" },
+                                retryable: { type: "boolean" },
+                                recoveryAction: { type: "string" }
+                            },
+                            required: ["code", "message", "retryable", "recoveryAction"],
+                            additionalProperties: false
+                        }
                     },
-                    required: ["ok", "storybookUrl", "mcpUrl", "mcpServers"]
+                    required: ["ok", "error"],
+                    additionalProperties: false
                 }
-            }
-        ]
+            ]
+        }
     };
 }
 function mcpToolAnnotations(name, policy) {
@@ -603,7 +1060,45 @@ function toolResult(value) {
     return { content, structuredContent };
 }
 function toolError(message) {
-    return { content: [{ type: "text", text: message }], isError: true };
+    return structuredToolError(message);
+}
+const BUILD_MCP_RECOVERY_ERROR_VALUES = {
+    platform_harness_timeout: { retryable: true, recoveryAction: "Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress." },
+    platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
+    artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
+    artifact_delete_plan_stale: { retryable: true, recoveryAction: "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken." },
+    artifact_app_bundle_changed_after_inspection: { retryable: true, recoveryAction: "Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash." },
+    artifact_app_bundle_hardlink_forbidden: { retryable: false, recoveryAction: "Replace the hard link with a regular file copied into appDir, then inspect again." },
+    artifact_app_auth_file_inside_app_dir: { retryable: false, recoveryAction: "Move TOPLINE_MCP_AUTH_FILE outside appDir, reconnect the Build MCP, then inspect again." },
+    artifact_app_manifest_not_found: { retryable: false, recoveryAction: "Create artifact-app.json inside appDir, or correct appDir, then inspect again." },
+    artifact_app_manifest_too_large: { retryable: false, recoveryAction: "Keep artifact-app.json below 512 KiB. Move application data and source into separate files, then inspect again." },
+    scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
+    artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." }
+};
+export const BUILD_MCP_RECOVERY_ERRORS = Object.freeze(Object.fromEntries(Object.entries(BUILD_MCP_RECOVERY_ERROR_VALUES).map(([code, guidance]) => [code, Object.freeze(guidance)])));
+function structuredToolError(message) {
+    const code = recoveryErrorCode(message);
+    const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable: /^platform_harness_http_error:5|timeout|rate_limited/.test(message), recoveryAction: "Inspect the code and message, correct the input if needed, then retry the same tool." };
+    const structuredContent = { ok: false, error: { code, message, ...selected } };
+    return {
+        content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
+        structuredContent,
+        isError: true
+    };
+}
+function recoveryErrorCode(message) {
+    const known = [
+        "artifact_delete_plan_stale",
+        "artifact_deploy_wait_timeout",
+        "artifact_app_scaffold_target_not_empty",
+        "platform_harness_timeout",
+        "platform_mcp_tool_error",
+        "scope_required"
+    ].find((candidate) => message.includes(candidate));
+    if (known)
+        return known;
+    const match = message.match(/(?:^|:)([a-z][a-z0-9_]{2,})(?::|$)/);
+    return match?.[1] ?? "topline_mcp_tool_failed";
 }
 const jsonSchemaValidator = new AjvJsonSchemaValidator();
 function validateJsonSchema(schema, value) {
@@ -630,9 +1125,30 @@ async function jsonHeaders(opts) {
         "MCP-Protocol-Version": opts.protocolVersion
     };
 }
+const inFlightBearerTokenRequests = new Map();
 export async function getBearerToken(opts) {
     if (opts.token?.trim())
         return opts.token.trim();
+    const key = [
+        path.resolve(opts.authFile),
+        platformBaseUrl(opts),
+        mcpSurface(opts),
+        [...opts.oauthScopes].sort().join(" ")
+    ].join("\0");
+    const existing = inFlightBearerTokenRequests.get(key);
+    if (existing)
+        return existing;
+    const pending = getOAuthBearerToken(opts);
+    inFlightBearerTokenRequests.set(key, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        if (inFlightBearerTokenRequests.get(key) === pending)
+            inFlightBearerTokenRequests.delete(key);
+    }
+}
+async function getOAuthBearerToken(opts) {
     const stored = await readStoredOAuthCredentials(opts);
     if (stored?.accessToken && stored.accessTokenExpiresAt && new Date(stored.accessTokenExpiresAt).getTime() - Date.now() > 60_000) {
         return stored.accessToken;
@@ -776,7 +1292,7 @@ async function readStoredOAuthCredentials(opts) {
         const issuer = typeof parsed.issuer === "string" ? parsed.issuer : "";
         const resource = typeof parsed.resource === "string" ? parsed.resource : "";
         const clientId = typeof parsed.clientId === "string" ? parsed.clientId : "";
-        const scopes = Array.isArray(parsed.scopes) ? parsed.scopes.filter((scope) => typeof scope === "string") : DEFAULT_OAUTH_SCOPES;
+        const scopes = Array.isArray(parsed.scopes) ? parsed.scopes.filter((scope) => typeof scope === "string") : [...DEFAULT_OAUTH_SCOPES];
         if (!issuer || !resource || !clientId)
             return null;
         const expectedIssuer = platformBaseUrl(opts);
@@ -890,6 +1406,15 @@ function platformBaseUrl(opts) {
 function mcpSurface(opts) {
     return opts.surface ?? "build";
 }
+function logicalArtifactAppDir(workspaceAppDir, manifest) {
+    if (workspaceAppDir === "." || workspaceAppDir.startsWith("artifact-apps/"))
+        return workspaceAppDir;
+    const manifestId = typeof manifest.id === "string" ? manifest.id.trim() : "";
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/.test(manifestId)) {
+        throw new Error("artifact_app_manifest_id_not_safe_for_source_root");
+    }
+    return `artifact-apps/${manifestId}`;
+}
 function defaultAuthFile(apiUrl, surface) {
     const key = createHash("sha256").update(`${platformBaseUrl({ apiUrl })}:${surface}`).digest("hex").slice(0, 16);
     return path.join(os.homedir(), ".topline", "build-mcp", `${key}.json`);
@@ -904,8 +1429,19 @@ function normalizeApiUrl(raw) {
     }
     if (url.protocol !== "http:" && url.protocol !== "https:")
         throw new Error("TOPLINE_API_URL must be an http(s) URL");
+    if (url.username || url.password)
+        throw new Error("TOPLINE_API_URL must not include credentials");
+    if (url.search || url.hash)
+        throw new Error("TOPLINE_API_URL must not include a query or fragment");
+    if (url.protocol !== "https:" && !isLoopbackHostname(url.hostname)) {
+        throw new Error("TOPLINE_API_URL must use https except for loopback development");
+    }
     return url.toString().replace(/\/$/g, "");
 }
+function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "[::1]" || normalized === "::1";
+}
 function firstEnv(env, ...keys) {
     for (const key of keys) {
         const value = env[key]?.trim();
@@ -948,8 +1484,22 @@ function toPosix(value) {
 }
 function redactSecrets(value, opts) {
     const token = opts.token?.trim();
-    const withoutStatic = token ? value.split(token).join("[redacted]") : value;
-    return withoutStatic
+    let redacted = token ? value.split(token).join("[redacted]") : value;
+    const localPaths = [opts.authFile, opts.workspaceRoot, os.homedir()]
+        .map((candidate) => path.resolve(candidate))
+        .filter((candidate, index, all) => candidate.length > path.parse(candidate).root.length && all.indexOf(candidate) === index)
+        .sort((left, right) => right.length - left.length);
+    for (const localPath of localPaths) {
+        const variants = new Set([
+            localPath,
+            toPosix(localPath),
+            JSON.stringify(localPath).slice(1, -1),
+            JSON.stringify(toPosix(localPath)).slice(1, -1)
+        ]);
+        for (const variant of variants)
+            redacted = redacted.split(variant).join("[local-path]");
+    }
+    return redacted
         .replace(/ovmcp_[A-Za-z0-9_-]+/g, "[redacted]")
         .replace(/tlmcp_(?:at|rt|code)_[A-Za-z0-9_-]+/g, "[redacted]");
 }