@jterrats/open-orchestra 0.5.5 → 1.0.1

package/dist/web-api.js

@@ -1,19 +1,24 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import http from "node:http";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { listAutonomousRuns } from "./autonomous-workflow.js";
+import { cancelRun, listAutonomousRuns } from "./autonomous-workflow.js";
 import { parsePromotionTarget, parseSkillRenderTarget, removeUndefined, } from "./command-utils.js";
-import { addEvidence, addTask, approveWorkflowGate, getTaskContext, listTasks, previewWorkflowGate, recordReview, updateTask, } from "./workflow-services.js";
+import { addEvidence, addTask, approveWorkflowGate, getWorkflowConfig, getTaskContext, listTasks, previewWorkflowGate, recordWorkflowGateDecision, recordReview, setRoleModelProvider, updateTask, } from "./workflow-services.js";
 import { listWebEvidence, readWorkspaceArtifact } from "./web-evidence.js";
+import { attachArtifactEvidence, previewWebArtifact } from "./web-artifacts.js";
 import { attachWebPlaywrightEvidence, getWebPlaywrightPlan, } from "./web-playwright.js";
+import { authorizeWebAction } from "./web-action-security.js";
 import { getWebRoleActivation } from "./web-roles.js";
+import { generateQaAutomationCoverage } from "./qa-coverage.js";
+import { repairRecoveryItem } from "./web-recovery.js";
 import { renderWebConsoleHtml } from "./web-console.js";
 import { renderSubagentProtocol } from "./subagent-protocol.js";
 import { recommendCollaborationFlow } from "./collaboration-flows.js";
 import { renderWorkflowTemplates, selectWorkflowTemplates, } from "./workflow-templates.js";
+import { listWorkflowEvents } from "./web-workflow-progress.js";
 import { loadPhasePlaybook } from "./phase-playbooks.js";
 import { decideTaskDelegation } from "./delegation-decision.js";
 import { addAgentLesson, planSkillsForTask, promoteAgentLessons, renderSkills, } from "./skills.js";
@@ -25,6 +30,8 @@ const DEFAULT_WEB_PORT = 3717;
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const CHART_JS_PATH = join(PACKAGE_ROOT, "node_modules/chart.js/dist/chart.umd.js");
 const WEB_CONSOLE_BUNDLE_PATH = join(PACKAGE_ROOT, "dist/assets/web-console.js");
+const REACT_WEB_CONSOLE_DIR = join(PACKAGE_ROOT, "dist/web-console");
+const REACT_WEB_CONSOLE_INDEX_PATH = join(REACT_WEB_CONSOLE_DIR, "index.html");
 const ORCHESTRA_CLI_PATH = join(PACKAGE_ROOT, "bin/orchestra.js");
 const execFileAsync = promisify(execFile);
 const routes = createWebReadRoutes();
@@ -52,6 +59,10 @@ const requestRoutes = {
         status: 200,
         body: await getWebPlaywrightPlan(root, requiredParam(url, "task")),
     }),
+    "/api/qa/coverage": async ({ root, url }) => ({
+        status: 200,
+        body: await generateQaAutomationCoverage(requiredParam(url, "task"), root),
+    }),
     "/api/delegation/decide": async ({ root, url }) => ({
         status: 200,
         body: await decideTaskDelegation(requiredParam(url, "task"), root, {
@@ -98,6 +109,15 @@ const requestRoutes = {
         }
         return { status: 200, body: selectWorkflowTemplates(task) };
     },
+    "/api/workflow/events": async ({ root, url }) => ({
+        status: 200,
+        body: await listWorkflowEvents(removeUndefined({
+            root,
+            task: stringParam(url, "task"),
+            run: stringParam(url, "run"),
+            limit: positiveIntegerParam(url, "limit") ?? 20,
+        })),
+    }),
     "/api/workflow/render": async ({ root, url }) => {
         const taskId = requiredParam(url, "task");
         const task = (await listTasks(root)).find((candidate) => candidate.id === taskId);
@@ -117,6 +137,10 @@ const requestRoutes = {
             }),
         };
     },
+    "/api/release/readiness": async ({ root }) => ({
+        status: 200,
+        body: await releaseReadinessView(root),
+    }),
 };
 export async function handleWebApiRequest(pathname, context) {
     const handler = routes[pathname];
@@ -163,11 +187,28 @@ export async function startWebApiServer(options = {}) {
             writeJson(response, result.status, result.body);
             return;
         }
+        if (request.method === "POST" &&
+            url.pathname === "/api/artifacts/evidence") {
+            const result = await handleArtifactEvidencePost(request, root);
+            writeJson(response, result.status, result.body);
+            return;
+        }
         if (request.method === "POST" && url.pathname === "/api/reviews/add") {
             const result = await handleReviewAddPost(request, root);
             writeJson(response, result.status, result.body);
             return;
         }
+        if (request.method === "POST" &&
+            url.pathname === "/api/provider/set-role") {
+            const result = await handleProviderSetRolePost(request, root);
+            writeJson(response, result.status, result.body);
+            return;
+        }
+        if (request.method === "POST" && url.pathname === "/api/recovery/repair") {
+            const result = await handleRecoveryRepairPost(request, root);
+            writeJson(response, result.status, result.body);
+            return;
+        }
         if (request.method === "POST" && url.pathname === "/api/workflow/start") {
             const result = await handleWorkflowStartPost(request, root);
             writeJson(response, result.status, result.body);
@@ -178,12 +219,23 @@ export async function startWebApiServer(options = {}) {
             writeJson(response, result.status, result.body);
             return;
         }
+        if (request.method === "POST" && url.pathname === "/api/workflow/cancel") {
+            const result = await handleWorkflowCancelPost(request, root);
+            writeJson(response, result.status, result.body);
+            return;
+        }
         if (request.method === "POST" &&
             url.pathname === "/api/workflow/gate-approve") {
             const result = await handleWorkflowGateApprovePost(request, root);
             writeJson(response, result.status, result.body);
             return;
         }
+        if (request.method === "POST" &&
+            url.pathname === "/api/workflow/gate-decision") {
+            const result = await handleWorkflowGateDecisionPost(request, root);
+            writeJson(response, result.status, result.body);
+            return;
+        }
         if (request.method === "POST" && url.pathname === "/api/lessons/add") {
             const result = await handleLessonAddPost(request, root);
             writeJson(response, result.status, result.body);
@@ -202,7 +254,7 @@ export async function startWebApiServer(options = {}) {
             return;
         }
         if (url.pathname === "/") {
-            writeHtml(response, renderWebConsoleHtml());
+            await writeConsoleIndex(response);
             return;
         }
         if (url.pathname === "/vendor/chart.umd.js") {
@@ -213,10 +265,22 @@ export async function startWebApiServer(options = {}) {
             await writeJavaScript(response, WEB_CONSOLE_BUNDLE_PATH);
             return;
         }
+        if (url.pathname.startsWith("/assets/")) {
+            await writeReactConsoleAsset(response, url.pathname);
+            return;
+        }
         if (url.pathname === "/api/artifacts") {
             await writeArtifactResponse(response, root, requiredParam(url, "path"));
             return;
         }
+        if (url.pathname === "/api/artifacts/preview") {
+            const result = await safeRequestRoute(async ({ root: requestRoot, url: requestUrl }) => ({
+                status: 200,
+                body: await previewWebArtifact(requestRoot, requiredParam(requestUrl, "path")),
+            }), { root, url, request });
+            writeJson(response, result.status, result.body);
+            return;
+        }
         const requestHandler = requestRoutes[url.pathname];
         const result = requestHandler
             ? await safeRequestRoute(requestHandler, { root, url, request })
@@ -236,6 +300,13 @@ async function handleTaskAddPost(request, root) {
     try {
         const input = (await readJsonBody(request));
         validateTaskAddInput(input);
+        await authorizeWebAction({
+            root,
+            taskId: input.id,
+            actor: "web-console",
+            action: "web task add",
+            paths: input.paths ?? [],
+        });
         return { status: 200, body: await addTask(input, root) };
     }
     catch (error) {
@@ -248,6 +319,13 @@ async function handleTaskUpdatePost(request, root) {
         if (!input.id) {
             throw new Error("id is required");
         }
+        await authorizeWebAction({
+            root,
+            taskId: input.id,
+            actor: "web-console",
+            action: "web task update",
+            paths: input.paths ?? [],
+        });
         return {
             status: 200,
             body: await updateTask({ ...input, id: input.id }, root),
@@ -261,22 +339,114 @@ async function handleEvidenceAddPost(request, root) {
     try {
         const input = (await readJsonBody(request));
         validateEvidencePostInput(input);
+        await authorizeWebAction(removeUndefined({
+            root,
+            taskId: input.task,
+            actor: input.role,
+            action: "web evidence add",
+            command: stringOrUndefined(input.command),
+            paths: stringArray(input.path),
+        }));
         return { status: 200, body: await addEvidence(input, root) };
     }
     catch (error) {
         return errorResult(error);
     }
 }
+async function handleArtifactEvidencePost(request, root) {
+    try {
+        const input = (await readJsonBody(request));
+        validateArtifactEvidenceInput(input);
+        await authorizeWebAction({
+            root,
+            taskId: input.task,
+            actor: input.role,
+            action: "web artifact evidence attach",
+            paths: [input.path],
+        });
+        return {
+            status: 200,
+            body: await attachArtifactEvidence(root, removeUndefined({
+                task: input.task,
+                role: input.role,
+                type: input.type,
+                path: input.path,
+                summary: input.summary,
+                runId: input.runId,
+            })),
+        };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
 async function handleReviewAddPost(request, root) {
     try {
         const input = (await readJsonBody(request));
         validateReviewPostInput(input);
+        await authorizeWebAction({
+            root,
+            taskId: input.task,
+            actor: input.role,
+            action: "web review add",
+        });
         return { status: 200, body: await recordReview(input, root) };
     }
     catch (error) {
         return errorResult(error);
     }
 }
+async function handleProviderSetRolePost(request, root) {
+    try {
+        const input = (await readJsonBody(request));
+        validateProviderSetRoleInput(input);
+        await authorizeWebAction({
+            root,
+            actor: "web-console",
+            action: "web provider role routing update",
+            command: `${input.role} ${input.provider}/${input.model}`,
+        });
+        const config = await getWorkflowConfig(root);
+        const current = config.providers?.byRole?.[input.role] ?? config.providers?.defaults;
+        const routing = {
+            provider: input.provider,
+            model: input.model,
+            fallbacks: input.fallbacks ?? current?.fallbacks ?? [],
+            maxTokens: input.maxTokens ?? current?.maxTokens ?? 8000,
+            maxCostUsd: input.maxCostUsd ?? current?.maxCostUsd ?? 1,
+            timeoutMs: input.timeoutMs ?? current?.timeoutMs ?? 120000,
+            retries: input.retries ?? current?.retries ?? 0,
+            requiredCapabilities: input.requiredCapabilities ?? current?.requiredCapabilities ?? [],
+        };
+        return {
+            status: 200,
+            body: await setRoleModelProvider(input.role, routing, root),
+        };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
+async function handleRecoveryRepairPost(request, root) {
+    try {
+        const input = (await readJsonBody(request));
+        validateRecoveryRepairInput(input);
+        await authorizeWebAction({
+            root,
+            actor: "web-console",
+            action: `web recovery ${input.action}`,
+            command: input.target,
+            confirmed: input.confirmed,
+        });
+        return {
+            status: 200,
+            body: await repairRecoveryItem(input, root),
+        };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
 async function handleWorkflowStartPost(request, root) {
     try {
         const input = (await readJsonBody(request));
@@ -284,6 +454,12 @@ async function handleWorkflowStartPost(request, root) {
             throw new Error("task is required");
         }
         const gates = parseWorkflowGates(input.gates);
+        await authorizeWebAction({
+            root,
+            taskId: input.task,
+            actor: "web-console",
+            action: "web workflow start",
+        });
         const execution = await runOrchestraCli(root, [
             "workflow",
             "run",
@@ -310,6 +486,12 @@ async function handleWorkflowResumePost(request, root) {
         if (!input.task || !input.run) {
             throw new Error("task and run are required");
         }
+        await authorizeWebAction({
+            root,
+            taskId: input.task,
+            actor: "web-console",
+            action: "web workflow resume",
+        });
         const execution = await runOrchestraCli(root, [
             "workflow",
             "run",
@@ -330,12 +512,38 @@ async function handleWorkflowResumePost(request, root) {
         return errorResult(error);
     }
 }
+async function handleWorkflowCancelPost(request, root) {
+    try {
+        const input = (await readJsonBody(request));
+        if (!input.run) {
+            throw new Error("run is required");
+        }
+        await authorizeWebAction(removeUndefined({
+            root,
+            actor: "web-console",
+            action: "web workflow cancel",
+            command: input.reason,
+        }));
+        return {
+            status: 200,
+            body: await cancelRun(root, input.run, input.reason ?? "Canceled from web console"),
+        };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
 async function handleWorkflowGateApprovePost(request, root) {
     try {
         const input = (await readJsonBody(request));
         if (!input.run || !input.gate || !input.approver || !input.rationale) {
             throw new Error("run, gate, approver, and rationale are required");
         }
+        await authorizeWebAction({
+            root,
+            actor: input.approver,
+            action: "web workflow gate approve",
+        });
         return {
             status: 200,
             body: await approveWorkflowGate({
@@ -350,6 +558,39 @@ async function handleWorkflowGateApprovePost(request, root) {
         return errorResult(error);
     }
 }
+async function handleWorkflowGateDecisionPost(request, root) {
+    try {
+        const input = (await readJsonBody(request));
+        if (!input.run || !input.gate || !input.reviewer || !input.rationale) {
+            throw new Error("run, gate, reviewer, and rationale are required");
+        }
+        if (!isWorkflowGateDecisionResult(input.result)) {
+            throw new Error("result must be one of: approve, block, changes");
+        }
+        await authorizeWebAction({
+            root,
+            actor: input.reviewer,
+            action: `web workflow gate ${input.result}`,
+            command: input.rationale,
+        });
+        return {
+            status: 200,
+            body: await recordWorkflowGateDecision({
+                runId: input.run,
+                gateId: input.gate,
+                reviewer: input.reviewer,
+                rationale: input.rationale,
+                result: input.result,
+            }, root),
+        };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
+function isWorkflowGateDecisionResult(result) {
+    return result === "approve" || result === "block" || result === "changes";
+}
 export function getWebServerAddress(server) {
     const address = server.address();
     if (!address) {
@@ -376,6 +617,13 @@ function writeHtml(response, body) {
     });
     response.end(body);
 }
+async function writeConsoleIndex(response) {
+    if (await fileExists(REACT_WEB_CONSOLE_INDEX_PATH)) {
+        writeHtml(response, await readFile(REACT_WEB_CONSOLE_INDEX_PATH, "utf8"));
+        return;
+    }
+    writeHtml(response, renderWebConsoleHtml());
+}
 async function writeJavaScript(response, filePath) {
     const bundle = await readFile(filePath, "utf8");
     response.writeHead(200, {
@@ -384,6 +632,52 @@ async function writeJavaScript(response, filePath) {
     });
     response.end(bundle);
 }
+async function writeReactConsoleAsset(response, pathname) {
+    const assetPath = resolve(REACT_WEB_CONSOLE_DIR, pathname.replace(/^\//, ""));
+    if (isOutsideDirectory(REACT_WEB_CONSOLE_DIR, assetPath)) {
+        writeJson(response, 400, {
+            error: "invalid_asset_path",
+            message: "asset path must stay inside the web console build directory",
+        });
+        return;
+    }
+    if (!(await fileExists(assetPath))) {
+        writeJson(response, 404, {
+            error: "not_found",
+            message: `unknown asset: ${pathname}`,
+        });
+        return;
+    }
+    const body = await readFile(assetPath);
+    response.writeHead(200, {
+        "content-type": contentTypeForPath(assetPath),
+        "cache-control": "no-store",
+    });
+    response.end(body);
+}
+function isOutsideDirectory(root, candidate) {
+    const pathFromRoot = relative(root, candidate);
+    return pathFromRoot.startsWith("..") || pathFromRoot === "";
+}
+async function fileExists(filePath) {
+    try {
+        return (await stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function contentTypeForPath(filePath) {
+    if (filePath.endsWith(".js"))
+        return "text/javascript; charset=utf-8";
+    if (filePath.endsWith(".css"))
+        return "text/css; charset=utf-8";
+    if (filePath.endsWith(".svg"))
+        return "image/svg+xml";
+    if (filePath.endsWith(".json"))
+        return "application/json; charset=utf-8";
+    return "application/octet-stream";
+}
 async function safeRequestRoute(handler, context) {
     try {
         return await handler(context);
@@ -396,6 +690,13 @@ async function handlePlaywrightEvidencePost(request, root) {
     try {
         const input = (await readJsonBody(request));
         validatePlaywrightEvidenceInput(input);
+        await authorizeWebAction({
+            root,
+            taskId: input.task,
+            actor: "qa",
+            action: "web playwright evidence attach",
+            paths: [input.path],
+        });
         return {
             status: 200,
             body: await attachWebPlaywrightEvidence(root, input),
@@ -434,6 +735,26 @@ function validateEvidencePostInput(input) {
         throw new Error("task, role, type, and summary are required");
     }
 }
+function validateArtifactEvidenceInput(input) {
+    if (!input.task ||
+        !input.role ||
+        !input.type ||
+        !input.path ||
+        !input.summary) {
+        throw new Error("task, role, type, path, and summary are required");
+    }
+    if (![
+        "command",
+        "file",
+        "screenshot",
+        "trace",
+        "video",
+        "log",
+        "report",
+    ].includes(input.type)) {
+        throw new Error("invalid evidence type: " + input.type);
+    }
+}
 function validateReviewPostInput(input) {
     if (!input.task ||
         !input.role ||
@@ -446,6 +767,46 @@ function validateReviewPostInput(input) {
         input.severity = "low";
     }
 }
+function validateProviderSetRoleInput(input) {
+    if (!input.role || !input.provider || !input.model) {
+        throw new Error("role, provider, and model are required");
+    }
+    if (input.fallbacks && !Array.isArray(input.fallbacks)) {
+        throw new Error("fallbacks must be an array");
+    }
+    if (input.requiredCapabilities &&
+        !Array.isArray(input.requiredCapabilities)) {
+        throw new Error("requiredCapabilities must be an array");
+    }
+}
+function validateRecoveryRepairInput(input) {
+    if (input.action !== "release-lock" &&
+        input.action !== "remove-temp-file" &&
+        input.action !== "remove-file-lock") {
+        throw new Error("action must be one of: release-lock, remove-temp-file, remove-file-lock");
+    }
+    if (!input.target) {
+        throw new Error("target is required");
+    }
+    if (!input.confirmed) {
+        throw new Error("confirmed is required");
+    }
+}
+function stringOrUndefined(value) {
+    if (typeof value === "string" && value.trim() !== "") {
+        return value;
+    }
+    return undefined;
+}
+function stringArray(value) {
+    if (typeof value === "string" && value.trim() !== "") {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === "string");
+    }
+    return [];
+}
 function parseWorkflowGates(value) {
     const gates = value ?? "phase";
     if (!["none", "phase", "all"].includes(gates)) {
@@ -551,6 +912,14 @@ function stringParam(url, name) {
     const value = url.searchParams.get(name);
     return value && value.trim() !== "" ? value : undefined;
 }
+function positiveIntegerParam(url, name) {
+    const value = stringParam(url, name);
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
 function webEvidenceFilters(url) {
     const filters = {};
     const task = stringParam(url, "task");
@@ -567,6 +936,139 @@ async function taskReleaseReadinessReport(root, taskId) {
     const report = await generateReleaseReadinessReport(root);
     return report.tasks.find((task) => task.taskId === taskId) ?? null;
 }
+async function releaseReadinessView(root) {
+    const [report, tasks, packageInfo, commits] = await Promise.all([
+        generateReleaseReadinessReport(root),
+        listTasks(root),
+        readPackageInfo(),
+        recentCommits(root),
+    ]);
+    const closedTasks = tasks
+        .filter((task) => ["approved", "done"].includes(task.status))
+        .map((task) => ({
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        ownerRole: task.ownerRole,
+    }));
+    const pendingTasks = tasks
+        .filter((task) => ["pending", "ready", "in_progress", "blocked", "review"].includes(task.status))
+        .map((task) => ({
+        id: task.id,
+        title: task.title,
+        status: task.status,
+    }));
+    const checks = releaseChecks(report, pendingTasks.length);
+    return {
+        version: String(packageInfo.version ?? "unknown"),
+        commits,
+        closedTasks,
+        pendingTasks,
+        checks,
+        criticalBlockers: checks
+            .filter((check) => check.blocking && !check.passed)
+            .map((check) => check.label),
+        acceptedRisks: report.acceptedRisks,
+        summary: renderReleaseSummary({
+            version: String(packageInfo.version ?? "unknown"),
+            report,
+            closedTaskCount: closedTasks.length,
+            pendingTaskCount: pendingTasks.length,
+            checks,
+        }),
+        report,
+    };
+}
+async function readPackageInfo() {
+    return JSON.parse(await readFile(join(PACKAGE_ROOT, "package.json"), "utf8"));
+}
+async function recentCommits(root) {
+    try {
+        const { stdout } = await execFileAsync("git", ["log", "-5", "--pretty=format:%h %s"], { cwd: root });
+        return stdout.split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+function releaseChecks(report, pendingTaskCount) {
+    return [
+        {
+            id: "tests",
+            label: "Tests evidence",
+            passed: !report.knownGaps.some((gap) => /test|QA automation/i.test(gap)),
+            blocking: true,
+        },
+        {
+            id: "e2e",
+            label: "E2E evidence",
+            passed: report.tasks.some((task) => [
+                ...task.qaAutomationCoverage.commands,
+                ...task.qaAutomationCoverage.pageObjects,
+            ].some((item) => /e2e|playwright/i.test(item))),
+            blocking: false,
+        },
+        {
+            id: "docs",
+            label: "Docs or changelog evidence",
+            passed: !report.missingDocumentationEvidence,
+            blocking: false,
+        },
+        {
+            id: "site",
+            label: "Site or public documentation evidence",
+            passed: !report.missingDocumentationEvidence,
+            blocking: false,
+        },
+        {
+            id: "extension",
+            label: "Extension compatibility evidence",
+            passed: !report.knownGaps.some((gap) => /extension/i.test(gap)),
+            blocking: false,
+        },
+        {
+            id: "security",
+            label: "Security evidence",
+            passed: report.gaReadiness.criteria.some((criterion) => criterion.id === "security-evidence" && criterion.passed),
+            blocking: true,
+        },
+        {
+            id: "pending-issues",
+            label: "Pending local work",
+            passed: pendingTaskCount === 0,
+            blocking: false,
+        },
+        {
+            id: "critical-gates",
+            label: "Critical release gates",
+            passed: report.gaReadiness.blockers.length === 0 && report.passed,
+            blocking: true,
+        },
+    ];
+}
+function renderReleaseSummary({ version, report, closedTaskCount, pendingTaskCount, checks, }) {
+    return [
+        "# Release Readiness Summary",
+        "",
+        "- Version: " + version,
+        "- Decision: " + report.gaReadiness.decision,
+        "- Closed tasks: " + closedTaskCount,
+        "- Pending local work: " + pendingTaskCount,
+        "- Accepted risks: " + report.acceptedRisks.length,
+        "",
+        "## Checks",
+        ...checks.map((check) => "- " +
+            (check.passed ? "PASS" : "BLOCKED") +
+            " " +
+            check.label +
+            (check.blocking ? " (blocking)" : "")),
+        "",
+        "## Known Gaps",
+        ...(report.knownGaps.length > 0
+            ? report.knownGaps.slice(0, 20).map((gap) => "- " + gap)
+            : ["- none"]),
+    ].join("\n");
+}
 async function writeArtifactResponse(response, root, artifactPath) {
     try {
         const artifact = await readWorkspaceArtifact(root, artifactPath);