@topline-build/harness-mcp 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Topline Build MCP for creating and deploying artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,10 @@
   "homepage": "https://github.com/topline-build/topline-mcp#readme",
   "files": [
     "dist/",
-    "README.md"
+    "docs/generated/",
+    "CHANGELOG.md",
+    "README.md",
+    "scripts/certify-live.mjs"
   ],
   "bin": {
     "topline-mcp": "dist/cli.js"
@@ -32,14 +35,17 @@
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "docs:generate": "npm run build && node scripts/generate-docs.mjs",
+    "docs:check": "npm run build && node scripts/generate-docs.mjs --check",
     "mcp:stdio": "node dist/cli.js",
-    "prepack": "npm run build",
+    "prepack": "npm run docs:check",
     "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "certify:live": "node scripts/certify-live.mjs"
+    "certify:live": "node scripts/certify-live.mjs",
+    "certify:clients": "node scripts/certify-live.mjs --clients codex,claude,cursor"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/scripts/certify-live.mjs

@@ -0,0 +1,551 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createHarnessMcpStdioServer, parseHarnessOptions } from "../dist/index.js";
+
+const CLIENTS = ["codex", "claude", "cursor"];
+const EXPECTED_TOOLS = [
+  "platform_inspect_artifact_app",
+  "platform_deploy_artifact_app",
+  "platform_list_build_workspaces",
+  "platform_list_artifact_drafts",
+  "platform_wait_artifact_deploy",
+  "platform_run_artifact_smoke",
+  "platform_validate_artifact",
+  "platform_plan_artifact_draft_delete"
+];
+const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+const manifest = JSON.parse(await readFile(new URL("../docs/generated/build-mcp-manifest.json", import.meta.url), "utf8"));
+let args;
+
+if (process.argv[2] === "--certification-read-only-server") {
+  await runCertificationReadOnlyServer(process.argv.slice(3));
+} else {
+  args = parseArgs(process.argv.slice(2));
+  const report = args.selfTest ? selfTestReport() : await certify();
+  const output = `${JSON.stringify(report, null, 2)}\n`;
+  if (args.output) await writeFile(path.resolve(args.output), output, "utf8");
+  process.stdout.write(output);
+
+  if (report.status === "failed") process.exitCode = 1;
+  else if (args.requireAll && report.status !== "passed") process.exitCode = 2;
+}
+
+async function runCertificationReadOnlyServer(values) {
+  delete process.env.ANTHROPIC_API_KEY;
+  delete process.env.TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY;
+  const opts = parseHarnessOptions(values, withoutManualToken(process.env));
+  const server = createHarnessMcpStdioServer(opts, ["platform_inspect_artifact_app"]);
+  await server.connect(new StdioServerTransport());
+}
+
+async function certify() {
+  const workspaceRoot = path.resolve(process.env.TOPLINE_WORKSPACE_ROOT || process.cwd());
+  const appDir = process.env.TOPLINE_CERTIFICATION_APP_DIR?.trim();
+  const apiUrl = process.env.TOPLINE_API_URL?.trim();
+  const token = process.env.TOPLINE_MCP_TOKEN?.trim();
+  const prerequisites = {
+    apiUrl: apiUrl ? "available" : "missing",
+    appDir: appDir ? "available" : "missing",
+    credentials: token ? "manual_token" : "missing"
+  };
+  const clientResults = [];
+  for (const name of args.clients) {
+    clientResults.push(await probeClient(name, apiUrl, appDir, workspaceRoot));
+  }
+
+  let protocol;
+  if (!apiUrl || !appDir) {
+    protocol = skipped("missing_topline_url_or_certification_app");
+  } else {
+    protocol = await certifyProtocol({ apiUrl, token, appDir, workspaceRoot });
+  }
+
+  const checks = [...clientResults.flatMap((entry) => [entry.installation, entry.configuration, entry.protocolToolDiscovery, entry.clientMediatedRead]), protocol];
+  const failed = checks.some((entry) => entry.status === "failed");
+  const incomplete = checks.some((entry) => entry.status === "skipped");
+  return {
+    schemaVersion: 1,
+    status: failed ? "failed" : incomplete ? "partial" : "passed",
+    evidenceMode: "live",
+    package: { name: packageJson.name, version: packageJson.version },
+    protocol: { transport: manifest.protocol.transport, version: manifest.protocol.defaultVersion },
+    phase: args.phase,
+    auth: {
+      preferred: "oauth_browser_approval",
+      certificationMode: prerequisites.credentials,
+      boundary: "Noninteractive certification accepts only an operator-provided TOPLINE_MCP_TOKEN; normal client setup should use browser-approved OAuth."
+    },
+    prerequisites,
+    clients: clientResults,
+    workflow: protocol
+  };
+}
+
+async function probeClient(name, apiUrl, appDir, workspaceRoot) {
+  const command = clientCommand(name);
+  const version = run(command, ["--version"], process.cwd());
+  if (version.missing) {
+    return {
+      client: name,
+      installation: skipped("client_cli_not_installed"),
+      configuration: skipped("client_cli_not_installed"),
+      protocolToolDiscovery: skipped("client_cli_not_installed"),
+      clientMediatedRead: skipped("client_cli_not_installed")
+    };
+  }
+  if (!version.ok) {
+    return {
+      client: name,
+      installation: failed("client_version_command_failed", version.exitCode),
+      configuration: skipped("installation_failed"),
+      protocolToolDiscovery: skipped("installation_failed"),
+      clientMediatedRead: skipped("installation_failed")
+    };
+  }
+  if (!apiUrl) {
+    return {
+      client: name,
+      installation: passed({ versionDetected: true }),
+      configuration: skipped("topline_api_url_missing"),
+      protocolToolDiscovery: skipped("topline_api_url_missing"),
+      clientMediatedRead: skipped("topline_api_url_missing")
+    };
+  }
+
+  const scratch = await mkdtemp(path.join(os.tmpdir(), `topline-${name}-cert-`));
+  try {
+    const cliPath = path.resolve("dist/cli.js");
+    const configResult = await clientConfigurationProbe(name, command, scratch, cliPath, apiUrl, workspaceRoot);
+    const direct = await directToolDiscovery(name, apiUrl, workspaceRoot);
+    const mediated = args.agentMediated
+      ? await agentMediatedRead(name, command, scratch, apiUrl, appDir, workspaceRoot)
+      : skipped("agent_mediated_probe_not_requested");
+    return {
+      client: name,
+      installation: passed({ versionDetected: true }),
+      configuration: configResult,
+      protocolToolDiscovery: direct,
+      clientMediatedRead: mediated
+    };
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+
+async function clientConfigurationProbe(name, command, scratch, cliPath, apiUrl, workspaceRoot) {
+  const server = { command: process.execPath, args: [cliPath, "--url", apiUrl, "--workspace-root", workspaceRoot] };
+  if (name === "codex") {
+    const tomlServer = 'mcp_servers."topline-build"';
+    const result = run(command, [
+      "mcp", "list", "--json",
+      "-c", `${tomlServer}.command=${JSON.stringify(server.command)}`,
+      "-c", `${tomlServer}.args=${JSON.stringify(server.args)}`
+    ], scratch);
+    if (!result.ok) return failed("client_ephemeral_config_rejected", result.exitCode);
+    try {
+      JSON.parse(result.stdout);
+      return passed({ scope: "ephemeral" });
+    } catch {
+      return failed("client_config_output_invalid", result.exitCode);
+    }
+  }
+
+  const configDir = path.join(scratch, name === "cursor" ? ".cursor" : ".topline-cert");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "mcp.json");
+  await writeFile(configPath, JSON.stringify({ mcpServers: { "topline-build": server } }, null, 2), "utf8");
+  if (name === "claude") {
+    const added = run(command, ["mcp", "add-json", "--scope", "project", "topline-build", JSON.stringify({ type: "stdio", ...server })], scratch);
+    if (!added.ok) return failed("client_ephemeral_config_rejected", added.exitCode);
+    const result = run(command, ["mcp", "get", "topline-build"], scratch);
+    return result.ok ? passed({ scope: "temporary_project" }) : failed("client_ephemeral_config_not_listed", result.exitCode);
+  }
+  const result = run(command, ["mcp", "list"], scratch);
+  if (!result.ok) return failed("client_ephemeral_config_rejected", result.exitCode);
+  return result.stdout.includes("topline-build")
+    ? passed({ scope: "ephemeral", approval: "operator_managed" })
+    : skipped("cursor_project_mcp_requires_operator_approval");
+}
+
+async function agentMediatedRead(name, command, scratch, apiUrl, appDir, workspaceRoot) {
+  if (name !== "claude") return skipped("strict_client_tool_isolation_unavailable");
+  if (!appDir) return skipped("certification_app_missing");
+  const server = {
+    command: process.execPath,
+    env: {
+      ANTHROPIC_API_KEY: "",
+      TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY: ""
+    },
+    args: [
+      fileURLToPath(import.meta.url),
+      "--certification-read-only-server",
+      "--url", apiUrl,
+      "--workspace-root", workspaceRoot,
+      "--auth-file", path.join(scratch, "certification-auth.json"),
+      "--scopes", "harness:artifact:read"
+    ]
+  };
+  const prompt = `Use only the Topline Build MCP server. Call platform_inspect_artifact_app exactly once with appDir ${JSON.stringify(appDir)}. Do not call shell, file-write, deployment, smoke, or delete tools. If packageReady is true, respond with TOPLINE_CLIENT_READ_CERTIFIED. Otherwise explain only the returned error code.`;
+  const configDir = path.join(scratch, ".topline-agent-cert");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "mcp.json");
+  await writeFile(configPath, JSON.stringify({ mcpServers: { "topline-build": server } }, null, 2), "utf8");
+  const result = run(command, [
+    "--mcp-config", configPath, "--strict-mcp-config", "--safe-mode",
+    "--tools", "", "--allowedTools", "mcp__topline-build__platform_inspect_artifact_app",
+    "--permission-mode", "dontAsk", "--no-chrome", "--disable-slash-commands",
+    "--no-session-persistence", "--max-budget-usd", "0.25",
+    "-p", "--output-format", "stream-json", prompt
+  ], scratch, 180000, strictAgentEnvironment(process.env));
+  if (!result.ok) {
+    return authUnavailable(result.output)
+      ? skipped("provider_credentials_or_client_session_unavailable")
+      : failed("client_mediated_read_failed", result.exitCode);
+  }
+  const usedTool = hasToolCallEvidence(result.output, "platform_inspect_artifact_app");
+  const certified = hasAssistantCertificationEvidence(result.output);
+  return usedTool && certified
+    ? passed({ tool: "platform_inspect_artifact_app", providerModelUsed: true })
+    : failed("client_mediated_tool_evidence_missing", result.exitCode);
+}
+
+async function directToolDiscovery(clientName, apiUrl, workspaceRoot) {
+  const opts = parseHarnessOptions([], {
+    TOPLINE_API_URL: apiUrl,
+    TOPLINE_WORKSPACE_ROOT: workspaceRoot,
+    TOPLINE_MCP_TIMEOUT_MS: process.env.TOPLINE_MCP_TIMEOUT_MS || "120000"
+  });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const server = createHarnessMcpStdioServer(opts);
+  const client = new Client({ name: `${clientName}-certification`, version: "1" }, { capabilities: {} });
+  try {
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    const listed = await client.listTools();
+    const names = new Set(listed.tools.map((tool) => tool.name));
+    const missing = EXPECTED_TOOLS.filter((name) => !names.has(name));
+    return missing.length === 0
+      ? passed({ toolCount: listed.tools.length, protocolVersion: manifest.protocol.defaultVersion })
+      : failed("required_tools_missing", null, { missing });
+  } catch {
+    return failed("mcp_tools_list_failed");
+  } finally {
+    await client.close().catch(() => undefined);
+    await server.close().catch(() => undefined);
+  }
+}
+
+async function certifyProtocol({ apiUrl, token, appDir, workspaceRoot }) {
+  const opts = parseHarnessOptions([], {
+    TOPLINE_API_URL: apiUrl,
+    TOPLINE_MCP_TOKEN: token || "",
+    TOPLINE_WORKSPACE_ROOT: workspaceRoot,
+    TOPLINE_MCP_TIMEOUT_MS: process.env.TOPLINE_MCP_TIMEOUT_MS || "120000"
+  });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const server = createHarnessMcpStdioServer(opts);
+  const client = new Client({ name: "topline-build-live-certification", version: "1" }, { capabilities: {} });
+  try {
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    const listed = await client.listTools();
+    for (const name of EXPECTED_TOOLS) {
+      if (!listed.tools.some((tool) => tool.name === name)) return failed("required_tools_missing");
+    }
+    const invalid = await client.callTool({ name: "platform_inspect_artifact_app", arguments: { appDir, unexpected: true } });
+    const error = invalid.structuredContent?.error;
+    if (!invalid.isError || typeof error?.code !== "string" || typeof error?.retryable !== "boolean" || typeof error?.recoveryAction !== "string") {
+      return failed("structured_failure_contract_missing");
+    }
+    const inspected = structured(await client.callTool({ name: "platform_inspect_artifact_app", arguments: { appDir } }));
+    if (inspected.packageReady !== true) return failed("artifact_package_not_ready");
+    const planEvidence = {
+      status: "passed",
+      readOnlyTool: "platform_inspect_artifact_app",
+      packageReady: true,
+      bundleSha256: inspected.bundle.sha256,
+      structuredFailure: { code: error.code, retryable: error.retryable, recoveryPresent: true }
+    };
+    if (args.phase === "plan") {
+      return passed({ plan: planEvidence, apply: skipped("operator_review_required") });
+    }
+    if (!token) return skipped("manual_certification_token_missing", { plan: planEvidence });
+    if (!args.expectedBundleSha256) return failed("expected_bundle_sha256_required_for_apply", null, { plan: planEvidence });
+    if (args.expectedBundleSha256 !== inspected.bundle.sha256) return failed("reviewed_bundle_sha256_changed", null, { plan: planEvidence });
+
+    const deployed = structured(await client.callTool({
+      name: "platform_deploy_artifact_app",
+      arguments: {
+        appDir,
+        expectedBundleSha256: args.expectedBundleSha256,
+        title: `Build MCP certification ${new Date().toISOString()}`
+      }
+    }));
+    if (deployed.bundle?.sha256 !== args.expectedBundleSha256) return failed("deployed_bundle_sha256_mismatch");
+    const completed = deployed.operationId
+      ? structured(await client.callTool({
+          name: "platform_wait_artifact_deploy",
+          arguments: { artifactId: deployed.artifactId, operationId: deployed.operationId, timeoutSeconds: 600 }
+        }))
+      : deployed.deploy;
+    const smoke = structured(await client.callTool({ name: "platform_run_artifact_smoke", arguments: { artifactId: deployed.artifactId } }));
+    const validation = structured(await client.callTool({ name: "platform_validate_artifact", arguments: { artifactId: deployed.artifactId } }));
+    const deletePlan = structured(await client.callTool({ name: "platform_plan_artifact_draft_delete", arguments: { artifactId: deployed.artifactId } }));
+    let cleanup = skipped("cleanup_not_approved");
+    if (process.env.TOPLINE_CERTIFICATION_CLEANUP === "1") {
+      cleanup = passed(structured(await client.callTool({
+        name: "platform_delete_artifact_draft",
+        arguments: { artifactId: deployed.artifactId, confirmArtifactId: deployed.artifactId, planToken: deletePlan.planToken }
+      })));
+    }
+    if (validation.healthy !== true) return failed("artifact_validation_unhealthy");
+    return passed({
+      plan: planEvidence,
+      apply: {
+        status: "passed",
+        reviewedWriteTool: "platform_deploy_artifact_app",
+        exactBundleApplied: true,
+        artifactId: deployed.artifactId,
+        operationId: deployed.operationId ?? null,
+        taskStatus: completed?.taskStatus ?? null,
+        smokePhase: smoke.phase,
+        healthy: true,
+        deleteEffectsReviewed: Boolean(deletePlan.effects),
+        cleanup
+      }
+    });
+  } catch (error) {
+    return failed(classifyError(error));
+  } finally {
+    await client.close().catch(() => undefined);
+    await server.close().catch(() => undefined);
+  }
+}
+
+function selfTestReport() {
+  const toolName = "platform_inspect_artifact_app";
+  const promptOnly = JSON.stringify({ type: "user", content: `Call ${toolName} and print TOPLINE_CLIENT_READ_CERTIFIED.` });
+  const toolEvent = JSON.stringify({ type: "item.completed", item: { type: "mcp_tool_call", tool: toolName } });
+  const assistantEvent = JSON.stringify({ type: "item.completed", item: { type: "agent_message", text: "TOPLINE_CLIENT_READ_CERTIFIED" } });
+  const sanitized = withoutManualToken({
+    SAFE_VALUE: "kept",
+    TOPLINE_MCP_TOKEN: "topline-secret",
+    PLATFORM_MCP_TOKEN: "platform-secret",
+    OVERSITE_MCP_TOKEN: "legacy-secret"
+  });
+  const strictEnvironment = strictAgentEnvironment({
+    PATH: "kept-path",
+    USERPROFILE: "kept-profile",
+    AWS_ACCESS_KEY_ID: "aws-secret",
+    DATABASE_URL: "database-secret",
+    OPENAI_API_KEY: "openai-secret",
+    ANTHROPIC_API_KEY: "anthropic-secret",
+    CURSOR_API_KEY: "cursor-secret",
+    TOPLINE_MCP_TOKEN: "topline-secret"
+  });
+  const optedInStrictEnvironment = strictAgentEnvironment({
+    PATH: "kept-path",
+    ANTHROPIC_API_KEY: "anthropic-secret",
+    TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY: "1"
+  });
+  if (hasToolCallEvidence(promptOnly, toolName)
+    || !hasToolCallEvidence(toolEvent, toolName)
+    || hasAssistantCertificationEvidence(promptOnly)
+    || !hasAssistantCertificationEvidence(assistantEvent)
+    || sanitized.SAFE_VALUE !== "kept"
+    || "TOPLINE_MCP_TOKEN" in sanitized
+    || "PLATFORM_MCP_TOKEN" in sanitized
+    || "OVERSITE_MCP_TOKEN" in sanitized
+    || strictEnvironment.PATH !== "kept-path"
+    || strictEnvironment.USERPROFILE !== "kept-profile"
+    || ["AWS_ACCESS_KEY_ID", "DATABASE_URL", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "CURSOR_API_KEY", "TOPLINE_MCP_TOKEN"].some((key) => key in strictEnvironment)
+    || optedInStrictEnvironment.ANTHROPIC_API_KEY !== "anthropic-secret"
+    || "TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY" in optedInStrictEnvironment) {
+    throw new Error("client_tool_evidence_self_test_failed");
+  }
+  return {
+    schemaVersion: 1,
+    status: "passed",
+    evidenceMode: "simulated",
+    package: { name: packageJson.name, version: packageJson.version },
+    protocol: { transport: manifest.protocol.transport, version: manifest.protocol.defaultVersion },
+    phase: args.phase,
+    auth: {
+      preferred: "oauth_browser_approval",
+      certificationMode: "self_test",
+      boundary: "Self-test uses no credentials or external clients."
+    },
+    prerequisites: { apiUrl: "self_test", appDir: "self_test", credentials: "self_test" },
+    clients: args.clients.map((client) => ({
+      client,
+      installation: passed({ simulated: true }),
+      configuration: passed({ simulated: true, scope: "ephemeral" }),
+      protocolToolDiscovery: passed({ simulated: true, toolCount: manifest.tools.length, protocolVersion: manifest.protocol.defaultVersion }),
+      clientMediatedRead: passed({ simulated: true, tool: "platform_inspect_artifact_app", providerModelUsed: false })
+    })),
+    workflow: passed({
+      plan: { status: "passed", readOnlyTool: "platform_inspect_artifact_app", structuredFailure: { recoveryPresent: true } },
+      apply: { status: "passed", reviewedWriteTool: "platform_deploy_artifact_app", exactBundleApplied: true, simulated: true }
+    })
+  };
+}
+
+function parseArgs(values) {
+  const parsed = { agentMediated: false, clients: [...CLIENTS], expectedBundleSha256: null, output: null, phase: "plan", requireAll: false, selfTest: false };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--agent-mediated") parsed.agentMediated = true;
+    else if (value === "--clients") parsed.clients = required(values[++index], value).split(",").map((entry) => entry.trim());
+    else if (value === "--expected-bundle-sha256") parsed.expectedBundleSha256 = required(values[++index], value).toLowerCase();
+    else if (value === "--output") parsed.output = required(values[++index], value);
+    else if (value === "--phase") parsed.phase = required(values[++index], value);
+    else if (value === "--require-all") parsed.requireAll = true;
+    else if (value === "--self-test") parsed.selfTest = true;
+    else throw new Error(`Unknown argument: ${value}`);
+  }
+  if (!parsed.clients.length || parsed.clients.some((name) => !CLIENTS.includes(name))) throw new Error("--clients must contain codex, claude, and/or cursor.");
+  if (new Set(parsed.clients).size !== parsed.clients.length) throw new Error("--clients must not contain duplicates.");
+  if (!['plan', 'apply'].includes(parsed.phase)) throw new Error("--phase must be plan or apply.");
+  if (parsed.expectedBundleSha256 && !/^[0-9a-f]{64}$/.test(parsed.expectedBundleSha256)) throw new Error("--expected-bundle-sha256 must be 64 hexadecimal characters.");
+  return parsed;
+}
+
+function clientCommand(name) {
+  const configured = name === "codex"
+    ? process.env.TOPLINE_CERTIFICATION_CODEX_BIN
+    : name === "claude"
+      ? process.env.TOPLINE_CERTIFICATION_CLAUDE_BIN
+      : process.env.TOPLINE_CERTIFICATION_CURSOR_BIN;
+  const executable = configured || (name === "cursor" ? "cursor-agent" : name);
+  if (process.platform !== "win32") return { executable, prefix: [] };
+  const found = spawnSync("where.exe", [executable], { encoding: "utf8", windowsHide: true });
+  const candidates = (found.stdout || "").split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean);
+  const native = candidates.find((entry) => /\.exe$/i.test(entry));
+  if (native) return { executable: native, prefix: [] };
+  const adjacentPowerShell = candidates.find((entry) => /\.cmd$/i.test(entry) && existsSync(entry.replace(/\.cmd$/i, ".ps1")))?.replace(/\.cmd$/i, ".ps1");
+  const powerShell = candidates.find((entry) => /\.ps1$/i.test(entry)) || adjacentPowerShell;
+  if (powerShell) return { executable: "powershell.exe", prefix: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", powerShell] };
+  return { executable, prefix: [] };
+}
+
+function run(command, commandArgs, cwd, timeout = 30000, env = withoutManualToken(process.env)) {
+  const result = spawnSync(command.executable, [...command.prefix, ...commandArgs], {
+    cwd,
+    encoding: "utf8",
+    env,
+    timeout,
+    windowsHide: true
+  });
+  return {
+    ok: result.status === 0,
+    missing: result.error?.code === "ENOENT",
+    exitCode: result.status,
+    stdout: result.stdout || "",
+    output: `${result.stdout || ""}\n${result.stderr || ""}`
+  };
+}
+
+function authUnavailable(output) {
+  return /not logged in|not authenticated|authentication required|api key|login required|please login|sign in/i.test(output);
+}
+
+function hasToolCallEvidence(output, toolName) {
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim().startsWith("{")) continue;
+    try {
+      if (containsToolCall(JSON.parse(line), toolName)) return true;
+    } catch {
+      // Client diagnostics may be mixed with JSONL. Only structured tool events count.
+    }
+  }
+  return false;
+}
+
+function containsToolCall(value, toolName) {
+  if (!value || typeof value !== "object") return false;
+  const type = typeof value.type === "string" ? value.type : "";
+  if (/tool(?:_|-)?(?:use|call)|mcp_tool/i.test(type) && JSON.stringify(value).includes(toolName)) return true;
+  return Object.values(value).some((child) => Array.isArray(child)
+    ? child.some((entry) => containsToolCall(entry, toolName))
+    : containsToolCall(child, toolName));
+}
+
+function hasAssistantCertificationEvidence(output) {
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim().startsWith("{")) continue;
+    try {
+      if (containsAssistantCertificationEvidence(JSON.parse(line))) return true;
+    } catch {
+      // Client diagnostics may be mixed with JSONL. Only structured assistant output counts.
+    }
+  }
+  return false;
+}
+
+function containsAssistantCertificationEvidence(value) {
+  if (!value || typeof value !== "object") return false;
+  if (value.role === "user" || value.type === "user") return false;
+  const type = typeof value.type === "string" ? value.type : "";
+  const role = typeof value.role === "string" ? value.role : "";
+  if ((role === "assistant" || /agent_message|assistant|result/i.test(type))
+    && JSON.stringify(value).includes("TOPLINE_CLIENT_READ_CERTIFIED")) return true;
+  return Object.values(value).some((child) => Array.isArray(child)
+    ? child.some((entry) => containsAssistantCertificationEvidence(entry))
+    : containsAssistantCertificationEvidence(child));
+}
+
+function withoutManualToken(source) {
+  const env = { ...source };
+  delete env.TOPLINE_MCP_TOKEN;
+  delete env.PLATFORM_MCP_TOKEN;
+  delete env.OVERSITE_MCP_TOKEN;
+  return env;
+}
+
+function strictAgentEnvironment(source) {
+  const allowed = new Set([
+    "ALL_PROXY", "APPDATA", "CI", "COMSPEC", "FORCE_COLOR", "HTTP_PROXY", "HTTPS_PROXY",
+    "LANG", "LC_ALL", "LOCALAPPDATA", "NODE_EXTRA_CA_CERTS", "NO_COLOR", "NO_PROXY", "PATH",
+    "PATHEXT", "PROGRAMDATA", "SSL_CERT_DIR", "SSL_CERT_FILE", "SYSTEMROOT", "TEMP", "TMP",
+    "USERPROFILE", "WINDIR"
+  ]);
+  const env = Object.fromEntries(Object.entries(source).filter(([key]) => allowed.has(key.toUpperCase())));
+  if (source.TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY === "1" && source.ANTHROPIC_API_KEY) {
+    env.ANTHROPIC_API_KEY = source.ANTHROPIC_API_KEY;
+  }
+  return env;
+}
+
+function structured(result) {
+  if (result.isError) throw new Error(result.structuredContent?.error?.code || "mcp_tool_error");
+  return result.structuredContent;
+}
+
+function classifyError(error) {
+  const message = error instanceof Error ? error.message : "unknown";
+  return /^[a-z0-9_:-]+$/.test(message) ? message.slice(0, 120) : "certification_workflow_failed";
+}
+
+function passed(details = {}) {
+  return { status: "passed", ...details };
+}
+
+function skipped(reason, details = {}) {
+  return { status: "skipped", reason, ...details };
+}
+
+function failed(reason, exitCode = null, details = {}) {
+  return { status: "failed", reason, exitCode, ...details };
+}
+
+function required(value, flag) {
+  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value.`);
+  return value;
+}