stageflow 0.19.0 → 0.23.0

package/dist/server/http.js

@@ -2,7 +2,8 @@ import { readFile, access } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getCredentialSourceSettings, setCredentialSource, } from "../agent/providerAuth.js";
-import { handleProviderRoutes, providerAuthErrorBody, } from "./providerRoutes.js";
+import { mapProviderAuthError } from "../agent/providerInspect.js";
+import { handleProviderRoutes } from "./providerRoutes.js";
 import { handleProjectMcpRoutes } from "./projectMcpRoutes.js";
 import { createPipeline, parseCreatePipelineBody } from "../config/createPipeline.js";
 import { createStage, parseCreateStageBody } from "../config/createStage.js";
@@ -12,12 +13,13 @@ import { listSkills } from "../config/listSkills.js";
 import { artifactMediaType, readRunArtifact, readRunArtifactBytes, } from "../mcp/readArtifact.js";
 import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { PipelineValidationError } from "../runtime/pipelineValidationError.js";
 import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, } from "../runtime/settingsFile.js";
 import { isTaskFile } from "../runtime/taskInput.js";
 import { parseAskOperatorAnswer } from "../tools/askOperator.js";
 import { bootstrapStageflowHost, } from "./bootstrap.js";
 import { createHttpHost, DEFAULT_PORT, json, } from "./createHttpHost.js";
-import { mapRetryStageFailure, mapStartFailure } from "./operatorResults.js";
+import { mapRetryStageFailure, mapStartFailure, mapStoreLookupError, } from "./operatorResults.js";
 function textPlain(res, status, body) {
     res.writeHead(status, {
         "Content-Type": "text/plain; charset=utf-8",
@@ -178,480 +180,526 @@ export function defaultUiDistDir() {
     }
     return path.resolve(here, "../ui");
 }
-export async function startUiServer(options) {
-    const host = options.host ?? "127.0.0.1";
-    const port = options.port ?? DEFAULT_PORT;
-    const uiDistDir = options.uiDistDir ?? defaultUiDistDir();
-    const boot = await bootstrapStageflowHost(options);
-    const { manager, store, cwd, agentDir } = boot;
-    const providerAuthContext = boot.providerAuthContext;
-    return createHttpHost({
-        boot,
-        host,
-        port,
-        routes: async ({ req, res, url, pathname, method }) => {
-            if (isMutatingApi(method, pathname)) {
-                if (!assertLoopbackHttpAccess(req, res)) {
-                    return true;
-                }
-                if (isCredentialMutatingApi(method, pathname) &&
-                    !assertCredentialMutatingOrigin(req, res)) {
-                    return true;
-                }
+/**
+ * The full operator-console route surface: REST API (runs, stages,
+ * catalog, settings, providers) plus, when `uiDistDir` is given, static
+ * console UI file serving. Shared by `startUiServer` (browser-facing) and
+ * `startMcpServer` (headless global-service daemon) — both need the REST
+ * API; only the former needs the UI files.
+ */
+export function createOperatorRoutes(deps) {
+    const { manager, store, cwd, agentDir, rootDir, providerAuthContext, uiDistDir } = deps;
+    return async ({ req, res, url, pathname, method }) => {
+        if (isMutatingApi(method, pathname)) {
+            if (!assertLoopbackHttpAccess(req, res)) {
+                return true;
+            }
+            if (isCredentialMutatingApi(method, pathname) &&
+                !assertCredentialMutatingOrigin(req, res)) {
+                return true;
+            }
+        }
+        try {
+            if (method === "GET" && pathname === "/api/runs") {
+                json(res, 200, { runs: await store.listRuns() });
+                return true;
             }
-            try {
-                if (method === "GET" && pathname === "/api/runs") {
-                    json(res, 200, { runs: await store.listRuns() });
+            const artifactMatch = pathname.match(/^\/api\/runs\/([^/]+)\/artifact$/);
+            if (method === "GET" && artifactMatch) {
+                const runId = decodeURIComponent(artifactMatch[1] ?? "");
+                const artifactPath = url.searchParams.get("path");
+                if (artifactPath === null || artifactPath.trim().length === 0) {
+                    json(res, 400, { error: "path query parameter is required" });
                     return true;
                 }
-                const artifactMatch = pathname.match(/^\/api\/runs\/([^/]+)\/artifact$/);
-                if (method === "GET" && artifactMatch) {
-                    const runId = decodeURIComponent(artifactMatch[1] ?? "");
-                    const artifactPath = url.searchParams.get("path");
-                    if (artifactPath === null || artifactPath.trim().length === 0) {
-                        json(res, 400, { error: "path query parameter is required" });
-                        return true;
+                try {
+                    const mediaType = artifactMediaType(artifactPath);
+                    if (mediaType !== undefined) {
+                        const bytes = await readRunArtifactBytes(store, runId, artifactPath);
+                        res.writeHead(200, {
+                            "Content-Type": mediaType,
+                            "Content-Length": bytes.length,
+                        });
+                        res.end(bytes);
                     }
-                    try {
-                        const mediaType = artifactMediaType(artifactPath);
-                        if (mediaType !== undefined) {
-                            const bytes = await readRunArtifactBytes(store, runId, artifactPath);
-                            res.writeHead(200, {
-                                "Content-Type": mediaType,
-                                "Content-Length": bytes.length,
-                            });
-                            res.end(bytes);
-                        }
-                        else {
-                            const content = await readRunArtifact(store, runId, artifactPath);
-                            textPlain(res, 200, content);
-                        }
+                    else {
+                        const content = await readRunArtifact(store, runId, artifactPath);
+                        textPlain(res, 200, content);
                     }
-                    catch (err) {
-                        const message = err instanceof Error ? err.message : String(err);
-                        if (message === "Artifact path denied") {
-                            json(res, 403, { error: message });
-                            return true;
-                        }
-                        const notFound = message.startsWith("Run not found") ||
-                            message.startsWith("Artifact not found") ||
-                            /no such|not found/i.test(message);
-                        json(res, notFound ? 404 : 400, { error: message });
-                    }
-                    return true;
                 }
-                const verificationMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/verification$/);
-                if (method === "GET" && verificationMatch) {
-                    const runId = decodeURIComponent(verificationMatch[1] ?? "");
-                    const stageId = decodeURIComponent(verificationMatch[2] ?? "");
+                catch (err) {
+                    const mapped = mapStoreLookupError(err, { policy: "artifact" });
+                    const status = mapped.kind === "denied" ? 403 : mapped.status;
+                    json(res, status, { error: mapped.error });
+                }
+                return true;
+            }
+            const verificationMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/verification$/);
+            if (method === "GET" && verificationMatch) {
+                const runId = decodeURIComponent(verificationMatch[1] ?? "");
+                const stageId = decodeURIComponent(verificationMatch[2] ?? "");
+                try {
+                    json(res, 200, await readStageVerificationHistory(store, runId, stageId));
+                }
+                catch (err) {
+                    const mapped = mapStoreLookupError(err, { policy: "run" });
+                    json(res, mapped.status, { error: mapped.error });
+                }
+                return true;
+            }
+            if (method === "GET" && pathname.startsWith("/api/runs/")) {
+                const rest = pathname.slice("/api/runs/".length);
+                if (rest && !rest.includes("/")) {
                     try {
-                        json(res, 200, await readStageVerificationHistory(store, runId, stageId));
+                        json(res, 200, await store.readRun(decodeURIComponent(rest)));
                     }
                     catch (err) {
-                        const message = err instanceof Error ? err.message : String(err);
-                        const notFound = /not found|no such/i.test(message);
-                        json(res, notFound ? 404 : 500, { error: message });
+                        const mapped = mapStoreLookupError(err, { policy: "run" });
+                        json(res, 404, { error: mapped.error });
                     }
                     return true;
                 }
-                if (method === "GET" && pathname.startsWith("/api/runs/")) {
-                    const rest = pathname.slice("/api/runs/".length);
-                    if (rest && !rest.includes("/")) {
-                        try {
-                            json(res, 200, await store.readRun(decodeURIComponent(rest)));
-                        }
-                        catch (err) {
-                            json(res, 404, {
-                                error: err instanceof Error ? err.message : String(err),
-                            });
-                        }
-                        return true;
-                    }
+            }
+            if (method === "POST" && pathname === "/api/runs") {
+                const body = (await readJsonBody(req));
+                if (typeof body.pipeline !== "string" ||
+                    !body.pipeline.trim() ||
+                    body.task === undefined) {
+                    json(res, 400, { error: "task and pipeline are required" });
+                    return true;
                 }
-                if (method === "POST" && pathname === "/api/runs") {
-                    const body = (await readJsonBody(req));
-                    if (typeof body.pipeline !== "string" ||
-                        !body.pipeline.trim() ||
-                        body.task === undefined) {
-                        json(res, 400, { error: "task and pipeline are required" });
-                        return true;
-                    }
-                    if (typeof body.task !== "string" && !isTaskFile(body.task)) {
-                        json(res, 400, {
-                            error: "task must be a path string or TaskFile object (id and goal required)",
-                        });
-                        return true;
-                    }
-                    const result = await manager.startRun({
-                        task: body.task,
-                        pipeline: body.pipeline.trim(),
+                if (typeof body.task !== "string" && !isTaskFile(body.task)) {
+                    json(res, 400, {
+                        error: "task must be a path string or TaskFile object (id and goal required)",
                     });
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, mapStartFailure(result));
-                        return true;
-                    }
-                    json(res, 202, { runId: result.runId });
                     return true;
                 }
-                if (method === "POST" && pathname.match(/^\/api\/runs\/[^/]+\/rerun$/)) {
-                    const runId = decodeURIComponent(pathname.split("/")[3] ?? "");
-                    const result = await manager.rerun(runId);
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, mapStartFailure(result));
-                        return true;
-                    }
-                    json(res, 202, { runId: result.runId });
+                if (body.checkoutOverride !== undefined &&
+                    typeof body.checkoutOverride !== "string") {
+                    json(res, 400, { error: "checkoutOverride must be a string" });
                     return true;
                 }
-                const answerMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/answer$/);
-                if (method === "POST" && answerMatch) {
-                    const runId = decodeURIComponent(answerMatch[1] ?? "");
-                    const stageId = decodeURIComponent(answerMatch[2] ?? "");
-                    let answer;
-                    try {
-                        answer = parseAskOperatorAnswer(await readJsonBody(req));
-                    }
-                    catch (err) {
-                        json(res, 400, {
-                            error: err instanceof Error ? err.message : String(err),
-                        });
-                        return true;
-                    }
-                    const result = await manager.deliverAnswer(runId, stageId, answer);
-                    if (!result.ok) {
-                        json(res, result.status, { error: result.reason });
-                        return true;
-                    }
-                    json(res, 202, { ok: true });
+                if (body.skipGates !== undefined && typeof body.skipGates !== "boolean") {
+                    json(res, 400, { error: "skipGates must be a boolean" });
                     return true;
                 }
-                const feedbackDecisionMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/feedback-decision$/);
-                if (method === "POST" && feedbackDecisionMatch) {
-                    const runId = decodeURIComponent(feedbackDecisionMatch[1] ?? "");
-                    const stageId = decodeURIComponent(feedbackDecisionMatch[2] ?? "");
-                    let body;
-                    try {
-                        body = await readJsonBody(req);
-                    }
-                    catch {
-                        json(res, 400, { error: "Invalid JSON body" });
-                        return true;
-                    }
-                    if (body === null || typeof body !== "object" || Array.isArray(body)) {
-                        json(res, 400, { error: "Body must be a JSON object" });
+                for (const field of ["gitSha", "ciPrUrl", "ciJobUrl"]) {
+                    if (body[field] !== undefined && typeof body[field] !== "string") {
+                        json(res, 400, { error: `${field} must be a string` });
                         return true;
                     }
-                    const raw = body;
-                    if (raw.decision !== "extend" &&
-                        raw.decision !== "continue" &&
-                        raw.decision !== "abandon") {
+                }
+                let result;
+                try {
+                    result = await manager.startRun({
+                        task: body.task,
+                        pipeline: body.pipeline.trim(),
+                        ...(body.checkoutOverride !== undefined
+                            ? { checkoutOverride: body.checkoutOverride }
+                            : {}),
+                        ...(body.skipGates !== undefined ? { skipGates: body.skipGates } : {}),
+                        ...(body.gitSha !== undefined ? { gitSha: body.gitSha } : {}),
+                        ...(body.ciPrUrl !== undefined ? { ciPrUrl: body.ciPrUrl } : {}),
+                        ...(body.ciJobUrl !== undefined ? { ciJobUrl: body.ciJobUrl } : {}),
+                    });
+                }
+                catch (err) {
+                    if (err instanceof PipelineValidationError) {
                         json(res, 400, {
-                            error: "decision must be extend, continue, or abandon",
+                            error: "Pipeline validation failed",
+                            validation: err.result,
                         });
                         return true;
                     }
-                    if (raw.loopId !== undefined && typeof raw.loopId !== "string") {
-                        json(res, 400, { error: "loopId must be a string" });
-                        return true;
-                    }
-                    if (raw.reason !== undefined && typeof raw.reason !== "string") {
-                        json(res, 400, { error: "reason must be a string" });
-                        return true;
-                    }
-                    const result = await manager.decideFeedbackLoop(runId, stageId, {
-                        decision: raw.decision,
-                        ...(raw.loopId !== undefined ? { loopId: raw.loopId } : {}),
-                        ...(raw.reason !== undefined ? { reason: raw.reason } : {}),
-                    });
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, { error: result.reason });
-                        return true;
-                    }
-                    json(res, 202, {
-                        ok: true,
-                        effect: result.effect,
-                        loopId: result.loopId,
-                    });
-                    return true;
+                    throw err;
                 }
-                const retryMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/retry$/);
-                if (method === "POST" && retryMatch) {
-                    await readJsonBody(req);
-                    const runId = decodeURIComponent(retryMatch[1] ?? "");
-                    const stageId = decodeURIComponent(retryMatch[2] ?? "");
-                    const result = await manager.retryStage(runId, stageId);
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, mapRetryStageFailure(result));
-                        return true;
-                    }
-                    json(res, 202, {
-                        runId: result.runId,
-                        stageId: result.stageId,
-                        attemptIndex: result.attemptIndex,
-                    });
+                if (!result.ok) {
+                    json(res, result.status ?? 500, mapStartFailure(result));
                     return true;
                 }
-                const resumeMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/resume$/);
-                if (method === "POST" && resumeMatch) {
-                    await readJsonBody(req);
-                    const runId = decodeURIComponent(resumeMatch[1] ?? "");
-                    const stageId = decodeURIComponent(resumeMatch[2] ?? "");
-                    const result = await manager.resumeTimedOutStage(runId, stageId);
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, mapRetryStageFailure(result));
-                        return true;
-                    }
-                    json(res, 202, {
-                        runId: result.runId,
-                        stageId: result.stageId,
-                        attemptIndex: result.attemptIndex,
-                    });
+                json(res, 202, { runId: result.runId });
+                return true;
+            }
+            if (method === "POST" && pathname.match(/^\/api\/runs\/[^/]+\/rerun$/)) {
+                const runId = decodeURIComponent(pathname.split("/")[3] ?? "");
+                const result = await manager.rerun(runId);
+                if (!result.ok) {
+                    json(res, result.status ?? 500, mapStartFailure(result));
                     return true;
                 }
-                const recoverMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery$/);
-                if (method === "POST" && recoverMatch) {
-                    let body;
-                    try {
-                        body = await readJsonBody(req);
-                    }
-                    catch {
-                        json(res, 400, { error: "Invalid JSON body" });
-                        return true;
-                    }
-                    const guidance = body !== null && typeof body === "object" && !Array.isArray(body)
-                        ? body.guidance
-                        : undefined;
-                    if (guidance !== undefined && typeof guidance !== "string") {
-                        json(res, 400, { error: "guidance must be a string" });
-                        return true;
-                    }
-                    const runId = decodeURIComponent(recoverMatch[1] ?? "");
-                    const stageId = decodeURIComponent(recoverMatch[2] ?? "");
-                    const result = await manager.recoverManualStage(runId, stageId, guidance);
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, mapRetryStageFailure(result));
-                        return true;
-                    }
-                    json(res, 202, {
-                        runId: result.runId,
-                        stageId: result.stageId,
-                        attemptIndex: result.attemptIndex,
+                json(res, 202, { runId: result.runId });
+                return true;
+            }
+            const answerMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/answer$/);
+            if (method === "POST" && answerMatch) {
+                const runId = decodeURIComponent(answerMatch[1] ?? "");
+                const stageId = decodeURIComponent(answerMatch[2] ?? "");
+                let answer;
+                try {
+                    answer = parseAskOperatorAnswer(await readJsonBody(req));
+                }
+                catch (err) {
+                    json(res, 400, {
+                        error: err instanceof Error ? err.message : String(err),
                     });
                     return true;
                 }
-                const stopRecoveryMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery\/stop$/);
-                if (method === "POST" && stopRecoveryMatch) {
-                    await readJsonBody(req);
-                    const runId = decodeURIComponent(stopRecoveryMatch[1] ?? "");
-                    const stageId = decodeURIComponent(stopRecoveryMatch[2] ?? "");
-                    const result = await manager.stopManualRecovery(runId, stageId);
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, { error: result.reason });
-                        return true;
-                    }
-                    json(res, 202, result);
-                    return true;
-                }
-                const abandonMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/abandon$/);
-                if (method === "POST" && abandonMatch) {
-                    await readJsonBody(req);
-                    const runId = decodeURIComponent(abandonMatch[1] ?? "");
-                    const stageId = decodeURIComponent(abandonMatch[2] ?? "");
-                    const result = await manager.abandonStage(runId, stageId);
-                    if (!result.ok) {
-                        json(res, result.status ?? 500, {
-                            error: result.reason,
-                        });
-                        return true;
-                    }
-                    json(res, 202, {
-                        ok: true,
-                        runId: result.runId,
-                        stageId: result.stageId,
-                    });
+                const result = await manager.deliverAnswer(runId, stageId, answer);
+                if (!result.ok) {
+                    json(res, result.status, { error: result.reason });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/tasks") {
-                    const catalog = await browseCatalog(cwd);
-                    json(res, 200, { tasks: catalog.tasks });
+                json(res, 202, { ok: true });
+                return true;
+            }
+            const feedbackDecisionMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/feedback-decision$/);
+            if (method === "POST" && feedbackDecisionMatch) {
+                const runId = decodeURIComponent(feedbackDecisionMatch[1] ?? "");
+                const stageId = decodeURIComponent(feedbackDecisionMatch[2] ?? "");
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON body" });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/pipelines") {
-                    const catalog = await browseCatalog(cwd);
-                    json(res, 200, { pipelines: catalog.pipelines });
+                if (body === null || typeof body !== "object" || Array.isArray(body)) {
+                    json(res, 400, { error: "Body must be a JSON object" });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/stages") {
-                    json(res, 404, {
-                        error: "Global stage library removed; stages are pipeline-scoped",
+                const raw = body;
+                if (raw.decision !== "extend" &&
+                    raw.decision !== "continue" &&
+                    raw.decision !== "abandon") {
+                    json(res, 400, {
+                        error: "decision must be extend, continue, or abandon",
                     });
                     return true;
                 }
-                if (method === "POST" && pathname === "/api/stages") {
-                    let body;
-                    try {
-                        body = await readJsonBody(req);
-                    }
-                    catch {
-                        json(res, 400, { error: "Invalid JSON body" });
-                        return true;
-                    }
-                    const parsed = parseCreateStageBody(body);
-                    if ("ok" in parsed) {
-                        json(res, parsed.status, { error: parsed.error });
-                        return true;
-                    }
-                    const ctx = await resolveStageflowContext(cwd);
-                    if (!ctx.isGitProject) {
-                        json(res, 400, {
-                            error: "Project root not found; initialize stageflow.yaml in a git repo",
-                        });
-                        return true;
-                    }
-                    const result = await createStage(ctx.projectRoot, parsed);
-                    if (!result.ok) {
-                        json(res, result.status, { error: result.error });
-                        return true;
-                    }
-                    json(res, 201, result.stage);
+                if (raw.loopId !== undefined && typeof raw.loopId !== "string") {
+                    json(res, 400, { error: "loopId must be a string" });
                     return true;
                 }
-                if (method === "POST" && pathname === "/api/pipelines") {
-                    let body;
-                    try {
-                        body = await readJsonBody(req);
-                    }
-                    catch {
-                        json(res, 400, { error: "Invalid JSON body" });
-                        return true;
-                    }
-                    const parsed = parseCreatePipelineBody(body);
-                    if ("ok" in parsed) {
-                        json(res, parsed.status, { error: parsed.error });
-                        return true;
-                    }
-                    const ctx = await resolveStageflowContext(cwd);
-                    if (!ctx.isGitProject) {
-                        json(res, 400, {
-                            error: "Project root not found; initialize stageflow.yaml in a git repo",
-                        });
-                        return true;
-                    }
-                    const result = await createPipeline(ctx.projectRoot, parsed);
-                    if (!result.ok) {
-                        json(res, result.status, { error: result.error });
-                        return true;
-                    }
-                    json(res, 201, result.pipeline);
+                if (raw.reason !== undefined && typeof raw.reason !== "string") {
+                    json(res, 400, { error: "reason must be a string" });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/models") {
-                    const catalog = await browseCatalog(cwd);
-                    json(res, 200, { models: catalog.models });
+                const result = await manager.decideFeedbackLoop(runId, stageId, {
+                    decision: raw.decision,
+                    ...(raw.loopId !== undefined ? { loopId: raw.loopId } : {}),
+                    ...(raw.reason !== undefined ? { reason: raw.reason } : {}),
+                });
+                if (!result.ok) {
+                    json(res, result.status ?? 500, { error: result.reason });
+                    return true;
+                }
+                json(res, 202, {
+                    ok: true,
+                    effect: result.effect,
+                    loopId: result.loopId,
+                });
+                return true;
+            }
+            const retryMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/retry$/);
+            if (method === "POST" && retryMatch) {
+                await readJsonBody(req);
+                const runId = decodeURIComponent(retryMatch[1] ?? "");
+                const stageId = decodeURIComponent(retryMatch[2] ?? "");
+                const result = await manager.retryStage(runId, stageId);
+                if (!result.ok) {
+                    json(res, result.status ?? 500, mapRetryStageFailure(result));
                     return true;
                 }
-                if (await handleProviderRoutes(req, res, {
-                    cwd,
-                    readJsonBody,
-                    json,
-                    providerAuthContext,
-                })) {
+                json(res, 202, {
+                    runId: result.runId,
+                    stageId: result.stageId,
+                    attemptIndex: result.attemptIndex,
+                });
+                return true;
+            }
+            const resumeMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/resume$/);
+            if (method === "POST" && resumeMatch) {
+                await readJsonBody(req);
+                const runId = decodeURIComponent(resumeMatch[1] ?? "");
+                const stageId = decodeURIComponent(resumeMatch[2] ?? "");
+                const result = await manager.resumeTimedOutStage(runId, stageId);
+                if (!result.ok) {
+                    json(res, result.status ?? 500, mapRetryStageFailure(result));
                     return true;
                 }
-                if (await handleProjectMcpRoutes(req, res, {
-                    projectRoot: boot.rootDir,
-                    json,
-                })) {
+                json(res, 202, {
+                    runId: result.runId,
+                    stageId: result.stageId,
+                    attemptIndex: result.attemptIndex,
+                });
+                return true;
+            }
+            const recoverMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery$/);
+            if (method === "POST" && recoverMatch) {
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON body" });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/skills") {
-                    json(res, 200, await listSkills({ cwd, agentDir }));
+                const guidance = body !== null && typeof body === "object" && !Array.isArray(body)
+                    ? body.guidance
+                    : undefined;
+                if (guidance !== undefined && typeof guidance !== "string") {
+                    json(res, 400, { error: "guidance must be a string" });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/extensions") {
-                    json(res, 200, await listExtensions({ cwd, agentDir }));
+                const runId = decodeURIComponent(recoverMatch[1] ?? "");
+                const stageId = decodeURIComponent(recoverMatch[2] ?? "");
+                const result = await manager.recoverManualStage(runId, stageId, guidance);
+                if (!result.ok) {
+                    json(res, result.status ?? 500, mapRetryStageFailure(result));
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/health") {
-                    json(res, 200, manager.getHealth());
+                json(res, 202, {
+                    runId: result.runId,
+                    stageId: result.stageId,
+                    attemptIndex: result.attemptIndex,
+                });
+                return true;
+            }
+            const stopRecoveryMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery\/stop$/);
+            if (method === "POST" && stopRecoveryMatch) {
+                await readJsonBody(req);
+                const runId = decodeURIComponent(stopRecoveryMatch[1] ?? "");
+                const stageId = decodeURIComponent(stopRecoveryMatch[2] ?? "");
+                const result = await manager.stopManualRecovery(runId, stageId);
+                if (!result.ok) {
+                    json(res, result.status ?? 500, { error: result.reason });
                     return true;
                 }
-                if (method === "GET" && pathname === "/api/settings") {
-                    const health = manager.getHealth();
-                    const credential = getCredentialSourceSettings(cwd);
-                    json(res, 200, {
-                        maxConcurrent: health.maxConcurrent,
-                        ...credential,
+                json(res, 202, result);
+                return true;
+            }
+            const abandonMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/abandon$/);
+            if (method === "POST" && abandonMatch) {
+                await readJsonBody(req);
+                const runId = decodeURIComponent(abandonMatch[1] ?? "");
+                const stageId = decodeURIComponent(abandonMatch[2] ?? "");
+                const result = await manager.abandonStage(runId, stageId);
+                if (!result.ok) {
+                    json(res, result.status ?? 500, {
+                        error: result.reason,
                     });
                     return true;
                 }
-                if (method === "POST" && pathname === "/api/settings") {
-                    let body;
-                    try {
-                        body = await readJsonBody(req);
-                    }
-                    catch {
-                        json(res, 400, { error: "Invalid JSON body" });
-                        return true;
-                    }
-                    const record = body !== null && typeof body === "object" && !Array.isArray(body)
-                        ? body
-                        : {};
-                    const hasMax = Object.prototype.hasOwnProperty.call(record, "maxConcurrent");
-                    const hasCredentialSource = Object.prototype.hasOwnProperty.call(record, "credentialSource");
-                    if (!hasMax && !hasCredentialSource) {
-                        json(res, 400, {
-                            error: "maxConcurrent or credentialSource is required",
-                        });
-                        return true;
-                    }
-                    let health = manager.getHealth();
-                    if (hasMax) {
-                        const n = parseSlotCount(record.maxConcurrent);
-                        if (n === undefined) {
-                            json(res, 400, { error: INVALID_SLOT_COUNT_MESSAGE });
-                            return true;
-                        }
-                        health = manager.setMaxConcurrent(n);
-                    }
-                    let credential = getCredentialSourceSettings(cwd);
-                    if (hasCredentialSource) {
-                        try {
-                            credential = setCredentialSource(cwd, record.credentialSource);
-                        }
-                        catch (err) {
-                            const mapped = providerAuthErrorBody(err);
-                            json(res, mapped.status, mapped.body);
-                            return true;
-                        }
-                    }
-                    json(res, 200, {
-                        ...health,
-                        ...credential,
+                json(res, 202, {
+                    ok: true,
+                    runId: result.runId,
+                    stageId: result.stageId,
+                });
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/tasks") {
+                const catalog = await browseCatalog(cwd);
+                json(res, 200, { tasks: catalog.tasks });
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/pipelines") {
+                const catalog = await browseCatalog(cwd);
+                json(res, 200, { pipelines: catalog.pipelines });
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/stages") {
+                json(res, 404, {
+                    error: "Global stage library removed; stages are pipeline-scoped",
+                });
+                return true;
+            }
+            if (method === "POST" && pathname === "/api/stages") {
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON body" });
+                    return true;
+                }
+                const parsed = parseCreateStageBody(body);
+                if ("ok" in parsed) {
+                    json(res, parsed.status, { error: parsed.error });
+                    return true;
+                }
+                const ctx = await resolveStageflowContext(cwd);
+                if (!ctx.isGitProject) {
+                    json(res, 400, {
+                        error: "Project root not found; initialize stageflow.yaml in a git repo",
                     });
                     return true;
                 }
-                if (method === "GET") {
-                    const served = await serveStatic(res, uiDistDir, pathname);
-                    if (served)
-                        return true;
-                    json(res, 404, {
-                        error: "UI not built. Run npm run ui:build, or use Vite dev proxy.",
+                const result = await createStage(ctx.projectRoot, parsed);
+                if (!result.ok) {
+                    json(res, result.status, { error: result.error });
+                    return true;
+                }
+                json(res, 201, result.stage);
+                return true;
+            }
+            if (method === "POST" && pathname === "/api/pipelines") {
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON body" });
+                    return true;
+                }
+                const parsed = parseCreatePipelineBody(body);
+                if ("ok" in parsed) {
+                    json(res, parsed.status, { error: parsed.error });
+                    return true;
+                }
+                const ctx = await resolveStageflowContext(cwd);
+                if (!ctx.isGitProject) {
+                    json(res, 400, {
+                        error: "Project root not found; initialize stageflow.yaml in a git repo",
                     });
                     return true;
                 }
-                json(res, 404, { error: "Not found" });
+                const result = await createPipeline(ctx.projectRoot, parsed);
+                if (!result.ok) {
+                    json(res, result.status, { error: result.error });
+                    return true;
+                }
+                json(res, 201, result.pipeline);
                 return true;
             }
-            catch (err) {
-                if (!res.headersSent) {
-                    json(res, 500, {
-                        error: err instanceof Error ? err.message : String(err),
+            if (method === "GET" && pathname === "/api/models") {
+                const catalog = await browseCatalog(cwd);
+                json(res, 200, { models: catalog.models });
+                return true;
+            }
+            if (await handleProviderRoutes(req, res, {
+                cwd,
+                readJsonBody,
+                json,
+                providerAuthContext,
+            })) {
+                return true;
+            }
+            if (await handleProjectMcpRoutes(req, res, {
+                projectRoot: rootDir,
+                json,
+            })) {
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/skills") {
+                json(res, 200, await listSkills({ cwd, agentDir }));
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/extensions") {
+                json(res, 200, await listExtensions({ cwd, agentDir }));
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/health") {
+                json(res, 200, manager.getHealth());
+                return true;
+            }
+            if (method === "GET" && pathname === "/api/settings") {
+                const health = manager.getHealth();
+                const credential = getCredentialSourceSettings(cwd);
+                json(res, 200, {
+                    maxConcurrent: health.maxConcurrent,
+                    ...credential,
+                });
+                return true;
+            }
+            if (method === "POST" && pathname === "/api/settings") {
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON body" });
+                    return true;
+                }
+                const record = body !== null && typeof body === "object" && !Array.isArray(body)
+                    ? body
+                    : {};
+                const hasMax = Object.prototype.hasOwnProperty.call(record, "maxConcurrent");
+                const hasCredentialSource = Object.prototype.hasOwnProperty.call(record, "credentialSource");
+                if (!hasMax && !hasCredentialSource) {
+                    json(res, 400, {
+                        error: "maxConcurrent or credentialSource is required",
                     });
+                    return true;
+                }
+                let health = manager.getHealth();
+                if (hasMax) {
+                    const n = parseSlotCount(record.maxConcurrent);
+                    if (n === undefined) {
+                        json(res, 400, { error: INVALID_SLOT_COUNT_MESSAGE });
+                        return true;
+                    }
+                    health = manager.setMaxConcurrent(n);
+                }
+                let credential = getCredentialSourceSettings(cwd);
+                if (hasCredentialSource) {
+                    try {
+                        credential = setCredentialSource(cwd, record.credentialSource);
+                    }
+                    catch (err) {
+                        const mapped = mapProviderAuthError(err);
+                        json(res, mapped.status, mapped.body);
+                        return true;
+                    }
                 }
+                json(res, 200, {
+                    ...health,
+                    ...credential,
+                });
                 return true;
             }
-        },
+            if (method === "GET" && uiDistDir !== undefined) {
+                const served = await serveStatic(res, uiDistDir, pathname);
+                if (served)
+                    return true;
+                json(res, 404, {
+                    error: "UI not built. Run npm run ui:build, or use Vite dev proxy.",
+                });
+                return true;
+            }
+            json(res, 404, { error: "Not found" });
+            return true;
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                json(res, 500, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return true;
+        }
+    };
+}
+export async function startUiServer(options) {
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? DEFAULT_PORT;
+    const uiDistDir = options.uiDistDir ?? defaultUiDistDir();
+    const boot = await bootstrapStageflowHost(options);
+    const { manager, store, cwd, agentDir, rootDir } = boot;
+    const providerAuthContext = boot.providerAuthContext;
+    return createHttpHost({
+        boot,
+        host,
+        port,
+        routes: createOperatorRoutes({
+            manager,
+            store,
+            cwd,
+            agentDir,
+            rootDir,
+            providerAuthContext,
+            uiDistDir,
+        }),
     });
 }
 export { DEFAULT_PORT };