@agentstorm/server 0.2.5

package/dist/pipeline-service.js

@@ -0,0 +1,2844 @@
+// AgentStorm resident PipelineService implementation.
+// The product daemon owns workspace, agent, chat, pipeline, task, workflow and run lifecycles.
+import express from "express";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID, createHash } from "node:crypto";
+import { ArtifactStore, Kernel, PipelineCoordinator, PipelineRunStore, TaskRunner, nowBeijing, toBeijingIso, } from "@agentstorm/kernel";
+import { ensurePipelineSessionPaths, pipelineSessionPaths, writeSessionJsonAtomic, } from "@agentstorm/kernel";
+import { safeParseWorkflowSpec, parseTaskList, ApprovalCommentSchema, HumanInterventionActionSchema, PipelineStartInputSchema, ResourceRefSchema, WorkflowBundleSchema, } from "@agentstorm/protocol";
+import { buildPipelineStatusSummary } from "./pipeline-status.js";
+import { GlobalTemplateLibrary, } from "./template-library.js";
+import { assertInsidePackage, assertWorkflowDisplayName, latestWorkflowPackageVersion, listWorkflowPackageNames, readJsonFile, recordWorkflowPackageVersion, safePackageRelativePath, workflowPackageExists, workflowPackagePaths, workflowPromptRelativePath, writeJsonAtomic as writePackageJsonAtomic, } from "./workflow-package.js";
+export function statusWithRunKind(status, events) {
+    const created = events.find((event) => event.t === "run_created");
+    if (!created)
+        return status;
+    const runKind = created.runKind ?? (created.taskId ? "execute" : "plan");
+    return { ...status, runKind };
+}
+export function taskBelongsToMainAgent(task, mainAgentId) {
+    return (task.mainAgentId ?? task.agentId) === mainAgentId;
+}
+export async function createPipelineService(opts) {
+    // A fresh identity lets clients distinguish a daemon restart from a healthy
+    // continuation of the same in-process Pipeline runtime.
+    const serverId = randomUUID();
+    // Map workspaceId → Kernel. Default workspace = cwd.
+    const kernels = new Map();
+    // The template library is daemon-host scoped, not Workspace scoped. Its
+    // default root is $AGENTSTORM_HOME/templates and can be overridden by
+    // AGENTSTORM_TEMPLATE_HOME for an intentionally shared test/development
+    // installation.
+    // Do not touch the daemon user's template home until templates are requested.
+    // Apart from avoiding unnecessary disk work, lazy construction keeps health
+    // and existing Workflow routes usable in restricted test containers where
+    // the optional global template directory is not writable yet.
+    let templateLibrary = null;
+    const getTemplateLibrary = () => (templateLibrary ??= new GlobalTemplateLibrary());
+    function getOrCreateKernel(workspaceId, rootPath) {
+        const existing = kernels.get(workspaceId);
+        if (existing)
+            return existing;
+        const agentstormDir = path.join(rootPath, ".agentstorm");
+        const unboundRoot = path.join(agentstormDir, "unbound");
+        const unboundPipelineRoot = path.join(unboundRoot, "pipeline");
+        fs.mkdirSync(unboundPipelineRoot, { recursive: true });
+        const backend = opts.agentRuntime;
+        const kernel = new Kernel({
+            runsRoot: unboundPipelineRoot,
+            tasksRoot: path.join(unboundPipelineRoot, "tasks"),
+            layout: "session",
+            sessionRoot: unboundPipelineRoot,
+            backend,
+            cwd: rootPath,
+        });
+        const wk = {
+            workspaceId,
+            rootPath,
+            kernel,
+            backend,
+            taskRunners: new Map(),
+            coordinators: new Map(),
+            pipelineStore: new PipelineRunStore(unboundPipelineRoot, {
+                layout: "session",
+            }),
+            artifacts: new ArtifactStore(unboundPipelineRoot, { layout: "session" }),
+            agentIds: new Set(),
+            sessions: new Map(),
+        };
+        kernels.set(workspaceId, wk);
+        return wk;
+    }
+    function getOrCreateSession(workspace, agentId) {
+        const existing = workspace.sessions.get(agentId);
+        if (existing)
+            return existing;
+        const agentstormDir = path.join(workspace.rootPath, ".agentstorm");
+        const paths = pipelineSessionPaths(agentstormDir, agentId);
+        ensurePipelineSessionPaths(paths);
+        const kernel = new Kernel({
+            runsRoot: paths.pipelineRoot,
+            tasksRoot: paths.tasksRoot,
+            layout: "session",
+            sessionRoot: paths.pipelineRoot,
+            backend: workspace.backend,
+            cwd: workspace.rootPath,
+            mainAgentId: agentId,
+        });
+        const session = {
+            workspaceId: workspace.workspaceId,
+            rootPath: workspace.rootPath,
+            kernel,
+            backend: workspace.backend,
+            taskRunners: new Map(),
+            coordinators: new Map(),
+            pipelineStore: new PipelineRunStore(paths.pipelineRoot, {
+                layout: "session",
+            }),
+            artifacts: new ArtifactStore(paths.pipelineRoot, { layout: "session" }),
+            agentIds: new Set([agentId]),
+            sessions: new Map(),
+            sessionAgentId: agentId,
+        };
+        const existingSession = fs.existsSync(paths.sessionFile)
+            ? readSessionRecord(paths.sessionFile)
+            : null;
+        const legacyBinding = readLegacyAgentWorkflowBindings(workspace.rootPath)[agentId];
+        writeSessionJsonAtomic(paths.sessionFile, {
+            ...(existingSession ?? {}),
+            sessionId: agentId,
+            mainAgentId: agentId,
+            workspaceId: workspace.workspaceId,
+            ...(typeof existingSession?.workflowId === "string"
+                ? { workflowId: existingSession.workflowId }
+                : legacyBinding
+                    ? { workflowId: legacyBinding }
+                    : {}),
+            updatedAt: nowBeijing(),
+        });
+        workspace.sessions.set(agentId, session);
+        return session;
+    }
+    // Default workspace = cwd
+    getOrCreateKernel("default", opts.cwd);
+    // Find kernel by runId
+    function findKernelByRunId(runId) {
+        for (const wk of kernels.values()) {
+            try {
+                wk.kernel.status(runId);
+                return wk;
+            }
+            catch {
+                /* not here */
+            }
+            for (const session of wk.sessions.values()) {
+                try {
+                    session.kernel.status(runId);
+                    return session;
+                }
+                catch {
+                    /* not here */
+                }
+            }
+        }
+        return null;
+    }
+    // Find kernel by agentId. A main Agent exists before it has any tasks, so
+    // explicit bindings must be consulted before the legacy task scan.
+    function findKernelByAgentId(agentId) {
+        for (const wk of kernels.values()) {
+            const session = wk.sessions.get(agentId);
+            if (session)
+                return session;
+            if (wk.agentIds.has(agentId))
+                return wk;
+            const tasks = wk.kernel.tasks.list();
+            if (tasks.some((t) => t.agentId === agentId))
+                return wk;
+            for (const candidate of wk.sessions.values()) {
+                if (candidate.agentIds.has(agentId) ||
+                    candidate.kernel.tasks.list().some((t) => t.agentId === agentId))
+                    return candidate;
+            }
+        }
+        return null;
+    }
+    // === Routes ===
+    const router = new PipelineRouteRegistry();
+    router.get("/health", (_req, res) => {
+        res.json({
+            serverId,
+            version: "0.0.0",
+            tokenRequired: false,
+        });
+    });
+    // Paseo owns Workspace creation. The embedded Pipeline UI registers the
+    // daemon-issued workspace ID with its already-resolved directory before it
+    // accesses workflow or run routes. Keeping the mapping here gives every
+    // Workspace a distinct Kernel and .agentstorm directory instead of silently
+    // putting all sessions in the fallback `default` runtime.
+    router.post("/workspaces/:wid/register", (req, res) => {
+        const rootPath = typeof req.body?.rootPath === "string" ? req.body.rootPath.trim() : "";
+        if (!rootPath || !path.isAbsolute(rootPath) || !fs.existsSync(rootPath)) {
+            res
+                .status(400)
+                .json({ error: "rootPath must be an existing absolute directory" });
+            return;
+        }
+        if (!fs.statSync(rootPath).isDirectory()) {
+            res.status(400).json({ error: "rootPath must be a directory" });
+            return;
+        }
+        const normalizedRootPath = path.resolve(rootPath);
+        const existing = kernels.get(req.params.wid);
+        if (existing && existing.rootPath !== normalizedRootPath) {
+            res.status(409).json({
+                error: "workspace is already registered to another directory",
+            });
+            return;
+        }
+        const workspace = getOrCreateKernel(req.params.wid, normalizedRootPath);
+        res.json({
+            workspaceId: workspace.workspaceId,
+            rootPath: workspace.rootPath,
+        });
+    });
+    // The Pipeline UI registers its Paseo main Agent after the Workspace mapping.
+    // This lets an empty Pipeline resolve to the right Kernel before the first
+    // Task is added or a run starts.
+    router.post("/workspaces/:wid/agents/:agentId/register", (req, res) => {
+        const workspace = kernels.get(req.params.wid);
+        if (!workspace) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        workspace.agentIds.add(req.params.agentId);
+        getOrCreateSession(workspace, req.params.agentId);
+        res.json({
+            workspaceId: workspace.workspaceId,
+            agentId: req.params.agentId,
+        });
+    });
+    // --- Global template library ---
+    // These routes are still reached through Paseo's authenticated daemon proxy;
+    // the browser never gets a filesystem path or direct storage access.
+    router.get("/templates", (_req, res) => {
+        try {
+            res.json(getTemplateLibrary().list());
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.get("/templates/:id", (req, res) => {
+        try {
+            res.json(getTemplateLibrary().get(req.params.id));
+        }
+        catch (error) {
+            res.status(404).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/templates", (req, res) => {
+        try {
+            res
+                .status(201)
+                .json(getTemplateLibrary().create(req.body));
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.put("/templates/:id", (req, res) => {
+        try {
+            res.json(getTemplateLibrary().update(req.params.id, req.body, req.header("if-match") ?? undefined));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            res
+                .status(message.includes("ETag mismatch") ? 409 : 400)
+                .json({ error: message });
+        }
+    });
+    router.delete("/templates/:id", (req, res) => {
+        try {
+            getTemplateLibrary().delete(req.params.id);
+            res.json({ ok: true, id: req.params.id });
+        }
+        catch (error) {
+            res.status(404).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Paseo calls this before archiving a managed Pipeline Workspace. Pausing is
+    // deliberate: the kernel writes the normal human_command/node_paused audit
+    // events before the Workspace record disappears, and never silently lets a
+    // child Agent continue after its parent Workspace has been archived.
+    router.post("/workspaces/:wid/archive", async (req, res) => {
+        const workspace = kernels.get(req.params.wid);
+        if (!workspace) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const runIds = [];
+        const archivedAgentIds = [];
+        const runtimes = [workspace, ...workspace.sessions.values()];
+        for (const runtime of runtimes) {
+            for (const runner of runtime.taskRunners.values())
+                runner.pause();
+            for (const task of runtime.kernel.tasks.list()) {
+                if (!task.runId)
+                    continue;
+                try {
+                    runtime.kernel.pause(task.runId);
+                    runIds.push(task.runId);
+                    archivedAgentIds.push(...(await runtime.kernel.archiveRunAgents(task.runId)));
+                }
+                catch {
+                    // A persisted task can reference a run deleted by a previous cleanup.
+                }
+            }
+        }
+        res.json({
+            runIds,
+            archivedAgentIds: Array.from(new Set(archivedAgentIds)),
+        });
+    });
+    // --- Workflows ---
+    router.get("/workspaces/:wid/workflows", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const documents = listWorkflowPackageNames(wk.rootPath).flatMap((id) => {
+            try {
+                const files = workflowPackagePaths(wk.rootPath, id);
+                const raw = fs.readFileSync(files.workflow, "utf8");
+                const manifest = fs.existsSync(files.manifest)
+                    ? readJsonFile(files.manifest)
+                    : {};
+                const source = manifest.source;
+                return [
+                    {
+                        id,
+                        spec: JSON.parse(raw),
+                        etag: etagOf(raw),
+                        updatedAt: toBeijingIso(fs.statSync(files.workflow).mtime),
+                        version: latestWorkflowPackageVersion(files),
+                        ...(typeof manifest.description === "string"
+                            ? { description: manifest.description }
+                            : {}),
+                        ...(source &&
+                            typeof source === "object" &&
+                            !Array.isArray(source) &&
+                            typeof source.templateId === "string"
+                            ? {
+                                templateId: source
+                                    .templateId,
+                                ...(Number.isSafeInteger(source.templateVersion)
+                                    ? {
+                                        templateVersion: Number(source.templateVersion),
+                                    }
+                                    : {}),
+                            }
+                            : {}),
+                    },
+                ];
+            }
+            catch {
+                return [];
+            }
+        });
+        res.json(documents);
+    });
+    router.post("/workspaces/:wid/workflows", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const result = safeParseWorkflowSpec(req.body);
+        if (!result.success) {
+            res.status(400).json({ error: result.error });
+            return;
+        }
+        let id;
+        try {
+            id = assertWorkflowDisplayName(result.data.name || `workflow-${Date.now()}`);
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        if (workflowPackageExists(wk.rootPath, id)) {
+            res.status(409).json({ error: `Workflow “${id}” 已存在` });
+            return;
+        }
+        try {
+            validateWorkflowPromptReferences(result.data);
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        const files = workflowPackagePaths(wk.rootPath, id);
+        const raw = JSON.stringify(result.data, null, 2);
+        writePackageJsonAtomic(files.workflow, result.data);
+        writePackageJsonAtomic(files.layout, {});
+        writePackageJsonAtomic(files.manifest, {
+            schemaVersion: 1,
+            name: id,
+            description: "",
+            version: 1,
+            source: { kind: "blank" },
+            createdAt: nowBeijing(),
+            updatedAt: nowBeijing(),
+        });
+        ensureWorkflowPromptFiles(files.root, result.data);
+        const version = recordWorkflowPackageVersion(files, raw);
+        res.json({
+            id,
+            spec: result.data,
+            etag: etagOf(raw),
+            updatedAt: nowBeijing(),
+            version,
+        });
+    });
+    router.post("/workspaces/:wid/workflows/from-template", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const templateId = typeof req.body?.templateId === "string"
+            ? req.body.templateId.trim()
+            : "";
+        if (!templateId) {
+            res.status(400).json({ error: "templateId is required" });
+            return;
+        }
+        try {
+            const result = getTemplateLibrary().materialize(templateId, wk.rootPath, {
+                ...(req.body?.name ? { name: String(req.body.name) } : {}),
+                ...(req.body?.agentConfig
+                    ? { agentConfig: req.body.agentConfig }
+                    : {}),
+            });
+            res.status(201).json(result);
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Portable P4 bundle: graph + Prompt assets. Everything is kept inside one
+    // display-name Workflow package; the runtime later uses that package root
+    // as specDir, so @prompts/... is stable after export/import.
+    router.post("/workspaces/:wid/workflow-bundles", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const parsed = WorkflowBundleSchema.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: parsed.error });
+            return;
+        }
+        try {
+            const id = assertWorkflowDisplayName(parsed.data.spec.name);
+            if (workflowPackageExists(wk.rootPath, id)) {
+                res.status(409).json({ error: `Workflow “${id}” 已存在` });
+                return;
+            }
+            const files = workflowPackagePaths(wk.rootPath, id);
+            for (const [assetName, content] of Object.entries(parsed.data.assets)) {
+                const relative = safePackageRelativePath(assetName);
+                if (!relative || content.length > 8 * 1024 * 1024)
+                    throw new Error(`invalid workflow asset: ${assetName}`);
+                const target = path.resolve(files.root, relative);
+                assertInsidePackage(files.root, target);
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, content, "utf8");
+            }
+            const spec = rewriteBundlePromptRefs(parsed.data.spec, Object.keys(parsed.data.assets));
+            validateWorkflowPromptReferences(spec);
+            const raw = JSON.stringify(spec, null, 2);
+            writePackageJsonAtomic(files.workflow, spec);
+            writePackageJsonAtomic(files.layout, parsed.data.layout ?? {});
+            writePackageJsonAtomic(files.manifest, {
+                schemaVersion: 1,
+                name: id,
+                description: "",
+                version: 1,
+                source: { kind: "bundle" },
+                createdAt: nowBeijing(),
+                updatedAt: nowBeijing(),
+            });
+            ensureWorkflowPromptFiles(files.root, spec);
+            const version = recordWorkflowPackageVersion(files, raw);
+            res.json({
+                id,
+                spec,
+                etag: etagOf(raw),
+                updatedAt: nowBeijing(),
+                version,
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.get("/workspaces/:wid/workflows/:id/bundle", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const files = workflowPackagePaths(wk.rootPath, req.params.id);
+        if (!fs.existsSync(files.workflow)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        const specResult = safeParseWorkflowSpec(readJsonFile(files.workflow));
+        if (!specResult.success) {
+            res.status(500).json({ error: "stored workflow is invalid" });
+            return;
+        }
+        try {
+            res.json({
+                format: "agentstorm.workflow.bundle.v1",
+                spec: specResult.data,
+                assets: collectPromptAssets(files.root, specResult.data),
+                layout: fs.existsSync(files.layout)
+                    ? readJsonFile(files.layout)
+                    : {},
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Provider-aware skill discovery. The old mixed-directory scan is gone: the
+    // Paseo Provider owns discovery and only reports skills it can actually load
+    // for this workspace/model/mode combination.
+    router.post("/workspaces/:wid/skills", async (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const provider = typeof req.body?.provider === "string" ? req.body.provider.trim() : "";
+        const model = typeof req.body?.model === "string" ? req.body.model.trim() : "";
+        if (!provider || !model) {
+            res.status(400).json({ error: "provider and model are required" });
+            return;
+        }
+        if (!wk.backend.listSkills) {
+            res.json({ provider, status: "unsupported", skills: [] });
+            return;
+        }
+        try {
+            const skills = await wk.backend.listSkills({
+                provider,
+                model,
+                cwd: wk.rootPath,
+                ...(typeof req.body?.mode === "string" && req.body.mode.trim()
+                    ? { mode: req.body.mode.trim() }
+                    : {}),
+                ...(typeof req.body?.thinking === "string" && req.body.thinking.trim()
+                    ? { thinking: req.body.thinking.trim() }
+                    : {}),
+            });
+            res.json({
+                provider,
+                status: "ready",
+                skills: skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description ?? "",
+                    argumentHint: skill.argumentHint ?? "",
+                    source: "provider",
+                    loadable: true,
+                })),
+            });
+        }
+        catch (error) {
+            res.json({
+                provider,
+                status: "unavailable",
+                skills: [],
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Compatibility response for old clients. It deliberately returns no
+    // mixed skill list; callers must provide a Provider-aware request instead.
+    router.get("/workspaces/:wid/skills", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        res.json({ provider: null, status: "unsupported", skills: [] });
+    });
+    // A Workflow belongs to a Workspace, but the selected Workflow belongs to
+    // its persistent main Agent (the Paseo conversation). Keeping the binding
+    // per Agent prevents two Pipeline conversations in one Workspace from
+    // silently changing each other's next run.
+    router.get("/workspaces/:wid/agents/:agentId/workflow", async (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        // A Pipeline session has no implicit Workflow. Only an explicit
+        // per-Agent binding is a selection; even a Workspace with one Workflow
+        // must remain unbound until the user chooses “设为当前”.
+        const workflowId = readAgentWorkflowBindings(workspace.rootPath)[req.params.agentId] ?? null;
+        if (!workflowId) {
+            res.json({ workflowId });
+            return;
+        }
+        try {
+            const workflowPath = workflowPackagePaths(workspace.rootPath, workflowId).workflow;
+            const parsed = safeParseWorkflowSpec(readJsonFile(workflowPath));
+            res.json({
+                workflowId,
+                readiness: parsed.success
+                    ? await workflowReadinessWithBackend(path.dirname(workflowPath), parsed.data, workspace.backend, workspace.rootPath)
+                    : {
+                        ready: false,
+                        errors: ["stored workflow is invalid"],
+                        missingPromptAssets: [],
+                        missingSkills: [],
+                        agents: [],
+                    },
+            });
+        }
+        catch {
+            res.json({
+                workflowId,
+                readiness: {
+                    ready: false,
+                    errors: ["workflow definition cannot be read"],
+                    missingPromptAssets: [],
+                    missingSkills: [],
+                    agents: [],
+                },
+            });
+        }
+    });
+    router.put("/workspaces/:wid/agents/:agentId/workflow", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const workflowId = req.body?.workflowId;
+        if (typeof workflowId !== "string" || !isSafeWorkflowId(workflowId)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const workflowPath = workflowPackagePaths(workspace.rootPath, workflowId).workflow;
+        if (!fs.existsSync(workflowPath)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        writeAgentWorkflowBinding(workspace.rootPath, req.params.agentId, workflowId);
+        res.json({ workflowId });
+    });
+    // Scoped workflow reads/writes are used by the Paseo daemon proxy. Unlike
+    // the legacy global workflow routes below, these can never cross a Workspace
+    // boundary when two projects happen to use the same workflow name.
+    router.get("/workspaces/:wid/workflows/:id", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const files = workflowPackagePaths(wk.rootPath, req.params.id);
+        const fp = files.workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        const raw = fs.readFileSync(fp, "utf8");
+        const manifest = fs.existsSync(files.manifest)
+            ? readJsonFile(files.manifest)
+            : {};
+        const source = manifest.source;
+        res.json({
+            id: req.params.id,
+            spec: JSON.parse(raw),
+            etag: etagOf(raw),
+            updatedAt: toBeijingIso(fs.statSync(fp).mtime),
+            version: latestWorkflowPackageVersion(workflowPackagePaths(wk.rootPath, req.params.id)),
+            ...(typeof manifest.description === "string"
+                ? { description: manifest.description }
+                : {}),
+            ...(source &&
+                typeof source === "object" &&
+                !Array.isArray(source) &&
+                typeof source.templateId === "string"
+                ? {
+                    templateId: source
+                        .templateId,
+                    ...(Number.isSafeInteger(source.templateVersion)
+                        ? {
+                            templateVersion: Number(source.templateVersion),
+                        }
+                        : {}),
+                }
+                : {}),
+        });
+    });
+    router.delete("/workspaces/:wid/workflows/:id", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const workflowId = req.params.id;
+        const files = workflowPackagePaths(wk.rootPath, workflowId);
+        const fp = files.workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        // Deleting a template is an explicit user action. Clear any persistent
+        // session bindings together with the file instead of leaving a dangling
+        // Workflow ID that makes the next Pipeline page look broken.
+        const clearedAgentIds = clearAgentWorkflowBindings(wk.rootPath, workflowId);
+        invalidateWorkflowCoordinators(wk, workflowId);
+        fs.rmSync(files.root, { recursive: true, force: true });
+        res.json({ ok: true, workflowId, clearedAgentIds });
+    });
+    router.put("/workspaces/:wid/workflows/:id", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const result = safeParseWorkflowSpec(req.body);
+        if (!result.success) {
+            res.status(400).json({ error: result.error });
+            return;
+        }
+        const oldId = req.params.id;
+        const files = workflowPackagePaths(wk.rootPath, oldId);
+        const fp = files.workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        const existing = fs.readFileSync(fp, "utf8");
+        const ifMatch = req.headers["if-match"];
+        if (ifMatch && ifMatch !== etagOf(existing)) {
+            res.status(409).json({ error: "ETag mismatch" });
+            return;
+        }
+        let newId;
+        try {
+            newId = assertWorkflowDisplayName(result.data.name);
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        let targetFiles = files;
+        try {
+            validateWorkflowPromptReferences(result.data);
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        if (newId !== oldId) {
+            if (workflowPackageExists(wk.rootPath, newId)) {
+                res.status(409).json({ error: `Workflow “${newId}” 已存在` });
+                return;
+            }
+            targetFiles = workflowPackagePaths(wk.rootPath, newId);
+            fs.renameSync(files.root, targetFiles.root);
+            renameAgentWorkflowBindings(wk.rootPath, oldId, newId);
+        }
+        const raw = JSON.stringify(result.data, null, 2);
+        writePackageJsonAtomic(targetFiles.workflow, result.data);
+        const manifest = fs.existsSync(targetFiles.manifest)
+            ? readJsonFile(targetFiles.manifest)
+            : {};
+        writePackageJsonAtomic(targetFiles.manifest, {
+            schemaVersion: 1,
+            name: newId,
+            description: typeof manifest.description === "string" ? manifest.description : "",
+            version: Number.isSafeInteger(manifest.version)
+                ? Number(manifest.version) + 1
+                : 1,
+            ...(manifest.source && typeof manifest.source === "object"
+                ? { source: manifest.source }
+                : {}),
+            createdAt: typeof manifest.createdAt === "string"
+                ? manifest.createdAt
+                : nowBeijing(),
+            updatedAt: nowBeijing(),
+        });
+        ensureWorkflowPromptFiles(targetFiles.root, result.data);
+        const version = recordWorkflowPackageVersion(targetFiles, raw);
+        // Same-ID saves stay attached to the existing coordinator. Its active
+        // Schedulers reread this package at node boundaries, and future starts
+        // already load the file. A rename changes the coordinator key/specDir and
+        // therefore still requires invalidation.
+        if (newId !== oldId) {
+            invalidateWorkflowCoordinators(wk, oldId);
+            invalidateWorkflowCoordinators(wk, newId);
+        }
+        res.json({
+            id: newId,
+            spec: result.data,
+            etag: etagOf(raw),
+            updatedAt: nowBeijing(),
+            version,
+        });
+    });
+    router.get("/workspaces/:wid/workflows/:id/versions", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const fp = workflowPackagePaths(wk.rootPath, req.params.id).workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        res.json(listWorkflowVersions(workflowPackagePaths(wk.rootPath, req.params.id), fs.readFileSync(fp, "utf8")));
+    });
+    router.post("/workspaces/:wid/workflows/:id/versions/:version/restore", (req, res) => {
+        const wk = kernels.get(req.params.wid);
+        if (!wk) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const files = workflowPackagePaths(wk.rootPath, req.params.id);
+        const fp = files.workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        const existing = fs.readFileSync(fp, "utf8");
+        const ifMatch = req.headers["if-match"];
+        if (ifMatch && ifMatch !== etagOf(existing)) {
+            res.status(409).json({ error: "ETag mismatch" });
+            return;
+        }
+        const raw = readWorkflowVersion(files, Number(req.params.version));
+        if (!raw) {
+            res.status(404).json({ error: "workflow version not found" });
+            return;
+        }
+        const result = safeParseWorkflowSpec(JSON.parse(raw));
+        if (!result.success) {
+            res.status(400).json({ error: "workflow version is invalid" });
+            return;
+        }
+        ensureWorkflowPromptFiles(files.root, result.data);
+        const previousManifest = fs.existsSync(files.manifest)
+            ? readJsonFile(files.manifest)
+            : {};
+        writePackageJsonAtomic(files.workflow, result.data);
+        writePackageJsonAtomic(files.manifest, {
+            schemaVersion: 1,
+            name: req.params.id,
+            description: typeof previousManifest.description === "string"
+                ? previousManifest.description
+                : "",
+            version: Number.isSafeInteger(previousManifest.version)
+                ? Number(previousManifest.version) + 1
+                : 1,
+            ...(previousManifest.source &&
+                typeof previousManifest.source === "object"
+                ? { source: previousManifest.source }
+                : {}),
+            createdAt: typeof previousManifest.createdAt === "string"
+                ? previousManifest.createdAt
+                : nowBeijing(),
+            updatedAt: nowBeijing(),
+        });
+        const version = recordWorkflowPackageVersion(files, raw);
+        res.json({
+            id: req.params.id,
+            spec: result.data,
+            etag: etagOf(raw),
+            updatedAt: nowBeijing(),
+            version,
+        });
+    });
+    router.get("/workflows/:id", (req, res) => {
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        for (const wk of kernels.values()) {
+            const fp = workflowPackagePaths(wk.rootPath, req.params.id).workflow;
+            if (fs.existsSync(fp)) {
+                const raw = fs.readFileSync(fp, "utf8");
+                res.json({
+                    id: req.params.id,
+                    spec: JSON.parse(raw),
+                    etag: etagOf(raw),
+                    updatedAt: toBeijingIso(fs.statSync(fp).mtime),
+                });
+                return;
+            }
+        }
+        res.status(404).json({ error: "workflow not found" });
+    });
+    router.put("/workflows/:id", (req, res) => {
+        const result = safeParseWorkflowSpec(req.body);
+        if (!result.success) {
+            res.status(400).json({ error: result.error });
+            return;
+        }
+        if (!isSafeWorkflowId(req.params.id)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const ifMatch = req.headers["if-match"];
+        for (const wk of kernels.values()) {
+            const files = workflowPackagePaths(wk.rootPath, req.params.id);
+            const fp = files.workflow;
+            if (!fs.existsSync(fp))
+                continue;
+            const existing = fs.readFileSync(fp, "utf8");
+            if (ifMatch && ifMatch !== etagOf(existing)) {
+                res.status(409).json({ error: "ETag mismatch" });
+                return;
+            }
+            const raw = JSON.stringify(result.data, null, 2);
+            const tmp = `${fp}.${process.pid}.${Date.now()}.tmp`;
+            fs.writeFileSync(tmp, raw, "utf8");
+            fs.renameSync(tmp, fp);
+            const version = recordWorkflowPackageVersion(files, raw);
+            res.json({
+                id: req.params.id,
+                spec: result.data,
+                etag: etagOf(raw),
+                updatedAt: nowBeijing(),
+                version,
+            });
+            return;
+        }
+        res.status(404).json({ error: "workflow not found" });
+    });
+    // Workspace-scoped task and run routes are the daemon-proxy contract.  They
+    // deliberately do not fall back to the default kernel or scan every kernel:
+    // callers must prove their Workspace ID and its registered main Agent.
+    function scopedWorkspace(workspaceId) {
+        return kernels.get(workspaceId) ?? null;
+    }
+    function scopedAgent(workspaceId, agentId) {
+        const workspace = scopedWorkspace(workspaceId);
+        if (!workspace || !workspace.agentIds.has(agentId))
+            return null;
+        return getOrCreateSession(workspace, agentId);
+    }
+    function pipelineRunFor(workspace, pipelineRunId) {
+        const runtimes = [workspace, ...workspace.sessions.values()];
+        for (const runtime of runtimes) {
+            const run = runtime.pipelineStore.get(pipelineRunId);
+            if (run?.workspaceId === workspace.workspaceId)
+                return run;
+        }
+        return null;
+    }
+    function pipelineRuntimeFor(workspace, pipelineRunId) {
+        const runtimes = [workspace, ...workspace.sessions.values()];
+        for (const runtime of runtimes) {
+            const run = runtime.pipelineStore.get(pipelineRunId);
+            if (run?.workspaceId === workspace.workspaceId)
+                return runtime;
+        }
+        return null;
+    }
+    // Generic Artifact API. Node Agents call this through the authenticated
+    // Paseo tool catalog; the UI can use the same read endpoints for timelines
+    // and reports. Content is UTF-8 in this MVP, with a bounded atomic write.
+    router.post("/workspaces/:wid/pipelines/:pipelineRunId/artifacts", (req, res) => {
+        const workspace = scopedWorkspace(req.params.wid);
+        if (!workspace) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const runtime = pipelineRuntimeFor(workspace, req.params.pipelineRunId);
+        if (!runtime) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const body = req.body ?? {};
+        if (typeof body.nodeId !== "string" ||
+            typeof body.kind !== "string" ||
+            typeof body.content !== "string") {
+            res
+                .status(400)
+                .json({ error: "nodeId, kind and UTF-8 content are required" });
+            return;
+        }
+        try {
+            if (body.runId !== undefined && typeof body.runId !== "string")
+                throw new Error("runId must be a string");
+            if (body.taskId !== undefined && typeof body.taskId !== "string")
+                throw new Error("taskId must be a string");
+            const ref = runtime.artifacts.publish({
+                pipelineRunId: req.params.pipelineRunId,
+                nodeId: body.nodeId,
+                kind: body.kind,
+                content: body.content,
+                ...(typeof body.name === "string" ? { name: body.name } : {}),
+                ...(typeof body.mimeType === "string"
+                    ? { mimeType: body.mimeType }
+                    : {}),
+                ...(typeof body.runId === "string" ? { runId: body.runId } : {}),
+                ...(typeof body.taskId === "string" ? { taskId: body.taskId } : {}),
+            });
+            res.status(201).json({ artifact: ref });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.get("/workspaces/:wid/pipelines/:pipelineRunId/artifacts", (req, res) => {
+        const workspace = scopedWorkspace(req.params.wid);
+        if (!workspace) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const runtime = pipelineRuntimeFor(workspace, req.params.pipelineRunId);
+        if (!runtime) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        res.json({ artifacts: runtime.artifacts.list(req.params.pipelineRunId) });
+    });
+    router.get("/workspaces/:wid/pipelines/:pipelineRunId/artifacts/:artifactId", (req, res) => {
+        const workspace = scopedWorkspace(req.params.wid);
+        if (!workspace) {
+            res.status(404).json({ error: "workspace not found" });
+            return;
+        }
+        const runtime = pipelineRuntimeFor(workspace, req.params.pipelineRunId);
+        if (!runtime) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        try {
+            const stored = runtime.artifacts.get(req.params.pipelineRunId, req.params.artifactId);
+            if (!stored) {
+                res.status(404).json({ error: "artifact not found" });
+                return;
+            }
+            res.json({
+                artifact: stored.ref,
+                content: stored.content.toString("utf8"),
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    function coordinatorFor(workspace, agentId, workflowId, resources = []) {
+        const key = `${agentId}:${workflowId}`;
+        const existing = workspace.coordinators.get(key);
+        if (existing)
+            return existing;
+        const workflowFiles = workflowPackagePaths(workspace.rootPath, workflowId);
+        const workflowPath = workflowFiles.workflow;
+        if (!fs.existsSync(workflowPath))
+            throw new Error(`workflow not found: ${workflowId}`);
+        const parsed = safeParseWorkflowSpec(readJsonFile(workflowPath));
+        if (!parsed.success)
+            throw new Error(`invalid workflow spec: ${JSON.stringify(parsed.error)}`);
+        const coordinator = new PipelineCoordinator({
+            kernel: workspace.kernel,
+            agentstormRoot: workspace.pipelineStore.root,
+            workspaceId: workspace.workspaceId,
+            mainAgentId: agentId,
+            workflowId,
+            workflowVersion: latestWorkflowPackageVersion(workflowFiles),
+            spec: parsed.data,
+            specDir: workflowFiles.root,
+            resources,
+            layout: "session",
+        });
+        workspace.coordinators.set(key, coordinator);
+        // Reattach persisted non-terminal runs once per coordinator. This is
+        // intentionally fire-and-forget: the HTTP request can serve the durable
+        // PipelineRun immediately while reconciliation resumes in the background.
+        void coordinator.reconcile();
+        return coordinator;
+    }
+    function invalidateWorkflowCoordinators(workspace, workflowId) {
+        for (const key of workspace.coordinators.keys()) {
+            if (key.endsWith(`:${workflowId}`))
+                workspace.coordinators.delete(key);
+        }
+    }
+    function resolveBoundWorkflowId(workspace, agentId, requested) {
+        if (typeof requested === "string" && isSafeWorkflowId(requested))
+            return requested;
+        const bound = readAgentWorkflowBindings(workspace.rootPath)[agentId];
+        if (bound)
+            return bound;
+        throw new Error("no workflow bound to this Pipeline Agent");
+    }
+    function scopedRun(workspaceId, runId) {
+        const workspace = scopedWorkspace(workspaceId);
+        if (!workspace)
+            return null;
+        try {
+            workspace.kernel.status(runId);
+            return workspace;
+        }
+        catch {
+            for (const session of workspace.sessions.values()) {
+                try {
+                    session.kernel.status(runId);
+                    return session;
+                }
+                catch {
+                    /* continue */
+                }
+            }
+            return null;
+        }
+    }
+    // === Generic PipelineRun lifecycle ===
+    // This is the one entry point used by both the Pipeline UI and the Paseo
+    // Main Agent tool. Legacy /plan and /run routes below remain for migration,
+    // but new callers must not compose them themselves.
+    router.post("/workspaces/:wid/agents/:agentId/pipeline/start", async (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const parsedInput = PipelineStartInputSchema.safeParse(req.body ?? {});
+        if (!parsedInput.success) {
+            res.status(400).json({ error: parsedInput.error });
+            return;
+        }
+        let resources = parsedInput.data.resources ?? [];
+        for (const resource of resources) {
+            const relativePath = resource.workspaceRelativePath;
+            if (relativePath !== undefined &&
+                !isSafeWorkspaceRelativePath(relativePath)) {
+                res.status(400).json({
+                    error: "resource workspaceRelativePath must stay inside the workspace",
+                });
+                return;
+            }
+        }
+        const resourceIds = parsedInput.data.resourceIds;
+        if (resourceIds !== undefined) {
+            if (!Array.isArray(resourceIds) ||
+                resourceIds.some((id) => typeof id !== "string" || id.trim().length === 0)) {
+                res
+                    .status(400)
+                    .json({ error: "resourceIds must be a non-empty string array" });
+                return;
+            }
+            // IDs are opaque to AgentStorm. Paseo or a Workflow-specific tool owns
+            // resolving them to files/attachments; keeping them as attachment refs
+            // avoids accepting arbitrary host paths at this boundary.
+            resources = [
+                ...resources,
+                ...resourceIds.map((id) => ({
+                    id,
+                    type: "attachment",
+                })),
+            ];
+        }
+        const requestedTaskIds = req.body?.taskIds;
+        if (requestedTaskIds !== undefined &&
+            (!Array.isArray(requestedTaskIds) ||
+                requestedTaskIds.some((id) => typeof id !== "string" || id.trim().length === 0))) {
+            res.status(400).json({ error: "taskIds must be a string array" });
+            return;
+        }
+        try {
+            const workflowId = resolveBoundWorkflowId(workspace, req.params.agentId, req.body?.workflowId);
+            const workflowPath = workflowPackagePaths(workspace.rootPath, workflowId).workflow;
+            const parsedWorkflow = safeParseWorkflowSpec(readJsonFile(workflowPath));
+            if (!parsedWorkflow.success) {
+                res.status(409).json({
+                    error: "workflow is not ready",
+                    readiness: {
+                        ready: false,
+                        errors: ["stored workflow is invalid"],
+                        missingPromptAssets: [],
+                        missingSkills: [],
+                        agents: [],
+                    },
+                });
+                return;
+            }
+            const readiness = await workflowReadinessWithBackend(path.dirname(workflowPath), parsedWorkflow.data, workspace.backend, workspace.rootPath);
+            if (!readiness.ready) {
+                res.status(409).json({ error: "workflow is not ready", readiness });
+                return;
+            }
+            const coordinator = coordinatorFor(workspace, req.params.agentId, workflowId, resources);
+            const started = coordinator.start({
+                goal: parsedInput.data.goal,
+                ...(parsedInput.data.idempotencyKey
+                    ? { idempotencyKey: parsedInput.data.idempotencyKey }
+                    : {}),
+                ...(resources.length > 0 ? { resources } : {}),
+                ...(Array.isArray(requestedTaskIds)
+                    ? { taskIds: requestedTaskIds }
+                    : {}),
+            });
+            res.status(202).json({
+                run: started.run,
+                ...(started.planRunId ? { planRunId: started.planRunId } : {}),
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Extend the one current PipelineRun owned by this Main Agent. A completed
+    // run returns to planning on its existing PlanRun; no second PipelineRun is
+    // created and completed Execute tasks remain completed.
+    router.post("/workspaces/:wid/agents/:agentId/pipeline/extend", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const text = typeof req.body?.request === "string" ? req.body.request.trim() : "";
+        if (!text) {
+            res.status(400).json({ error: "request is required" });
+            return;
+        }
+        try {
+            const workflowId = resolveBoundWorkflowId(workspace, req.params.agentId);
+            let coordinator = coordinatorFor(workspace, req.params.agentId, workflowId);
+            let current = coordinator.list()[0];
+            if (!current) {
+                res.status(404).json({ error: "PipelineRun not found" });
+                return;
+            }
+            // The user may have selected a different template for the next start
+            // after this run completed. Extension still belongs to the Workflow
+            // recorded on the existing PipelineRun.
+            if (current.workflowId !== workflowId) {
+                coordinator = coordinatorFor(workspace, req.params.agentId, current.workflowId);
+                current = coordinator.get(current.id) ?? current;
+            }
+            res.status(202).json({
+                run: coordinator.extend(current.id, { text }),
+                planRunId: current.planRunId,
+            });
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.get("/workspaces/:wid/agents/:agentId/pipelines", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const boundWorkflowId = readAgentWorkflowBindings(workspace.rootPath)[req.params.agentId];
+        const workflows = boundWorkflowId ? [boundWorkflowId] : [];
+        const runs = new Map();
+        for (const workflowId of workflows) {
+            const coordinator = workspace.coordinators.get(`${req.params.agentId}:${workflowId}`);
+            for (const run of coordinator?.list() ?? [])
+                runs.set(run.id, run);
+        }
+        // A newly restarted daemon may not have a live Coordinator yet. Read
+        // persisted PipelineRun files through a temporary bound Coordinator.
+        if (runs.size === 0) {
+            for (const workflowId of workflows) {
+                try {
+                    for (const run of coordinatorFor(workspace, req.params.agentId, workflowId).list())
+                        runs.set(run.id, run);
+                }
+                catch {
+                    /* stale binding is reported by readiness, not list */
+                }
+            }
+        }
+        res.json([...runs.values()]);
+    });
+    router.get("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const run = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!run) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const coordinator = run.coordinator;
+        const approvals = coordinator.approvals(req.params.pipelineRunId);
+        res.json({
+            run: run.value,
+            approvals,
+            ...buildPipelineStatusSummary(run.value, approvals),
+        });
+    });
+    router.get("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/events", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const run = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!run) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const requestedOffset = Number.parseInt(String(req.query.from ?? "0"), 10);
+        const fromOffset = Number.isFinite(requestedOffset) && requestedOffset > 0
+            ? requestedOffset
+            : 0;
+        res.json(workspace.kernel.store.readPipelineEventsFromOffset(req.params.pipelineRunId, fromOffset));
+    });
+    router.get("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/approvals", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        res.json(found.coordinator.approvals(req.params.pipelineRunId));
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/approve", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        try {
+            const approvalId = typeof req.body?.approvalId === "string" ? req.body.approvalId : "";
+            const planRevision = Number.isInteger(req.body?.planRevision)
+                ? Number(req.body.planRevision)
+                : undefined;
+            const comments = ApprovalCommentSchema.array().parse(req.body?.comments ?? []);
+            res.json(found.coordinator.approve(approvalId, typeof req.body?.decidedBy === "string"
+                ? req.body.decidedBy
+                : "user", planRevision, comments));
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/reject", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        try {
+            const approvalId = typeof req.body?.approvalId === "string" ? req.body.approvalId : "";
+            const feedback = typeof req.body?.feedback === "string" ? req.body.feedback : "";
+            const planRevision = Number.isInteger(req.body?.planRevision)
+                ? Number(req.body.planRevision)
+                : undefined;
+            const comments = ApprovalCommentSchema.array().parse(req.body?.comments ?? []);
+            res.json(found.coordinator.reject(approvalId, feedback, typeof req.body?.decidedBy === "string"
+                ? req.body.decidedBy
+                : "user", planRevision, comments));
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.get("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/approvals/:approvalId", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        try {
+            const detail = found.coordinator.approvalPackage(req.params.approvalId);
+            if (detail.approval.pipelineRunId !== req.params.pipelineRunId) {
+                res.status(404).json({ error: "approval not found" });
+                return;
+            }
+            res.json(detail);
+        }
+        catch (error) {
+            res.status(404).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/control", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const action = req.body?.action;
+        if (!["pause", "resume", "cancel"].includes(action)) {
+            res.status(400).json({ error: "invalid Pipeline control action" });
+            return;
+        }
+        try {
+            res.json(found.coordinator.control(req.params.pipelineRunId, action));
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/resume", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const taskId = typeof req.body?.taskId === "string" ? req.body.taskId.trim() : "";
+        const nodeId = typeof req.body?.nodeId === "string" ? req.body.nodeId.trim() : "";
+        const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";
+        if (!taskId || !text) {
+            res.status(400).json({ error: "taskId and text are required" });
+            return;
+        }
+        // Older Paseo clients used the generic Pipeline resume endpoint for the
+        // synthetic `planner:<PipelineRunId>` card. A Plan Run is not a Task, so
+        // keep that request on the original Plan Run instead of asking the
+        // Execute task scope to resolve it.
+        if (taskId.startsWith("planner:") || taskId === found.value.planRunId) {
+            if (!nodeId) {
+                res.status(400).json({ error: "nodeId and text are required" });
+                return;
+            }
+            try {
+                res.json(found.coordinator.reopenPlan(req.params.pipelineRunId, {
+                    nodeId,
+                    text,
+                }));
+            }
+            catch (error) {
+                res.status(409).json({
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return;
+        }
+        try {
+            res.json(found.coordinator.resumeBlocked(req.params.pipelineRunId, {
+                taskId,
+                ...(nodeId ? { nodeId } : {}),
+                text,
+            }));
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Continue a completed Execute Run in place. This is deliberately separate
+    // from blocked resume: the task keeps the same runId and the Kernel appends
+    // a run_reopened event instead of creating another Execute attempt.
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/reopen", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const taskId = typeof req.body?.taskId === "string" ? req.body.taskId.trim() : "";
+        const nodeId = typeof req.body?.nodeId === "string" ? req.body.nodeId.trim() : "";
+        const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";
+        if (!taskId || !nodeId || !text) {
+            res.status(400).json({ error: "taskId, nodeId and text are required" });
+            return;
+        }
+        // See the corresponding `pipeline.resume` compatibility branch above:
+        // reopening a planner must preserve the Plan Run identity and never
+        // require an Execute Task record.
+        if (taskId.startsWith("planner:") || taskId === found.value.planRunId) {
+            try {
+                res.json(found.coordinator.reopenPlan(req.params.pipelineRunId, {
+                    nodeId,
+                    text,
+                }));
+            }
+            catch (error) {
+                res.status(409).json({
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return;
+        }
+        try {
+            res.json(found.coordinator.reopenDone(req.params.pipelineRunId, {
+                taskId,
+                nodeId,
+                text,
+            }));
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    // Structured Node Agent handoffs. The Node tool supplies the immutable
+    // PipelineRun/Kernel run/node scope; the coordinator remains the only code
+    // that turns the resulting Kernel event into Tasks or Execute work.
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/plan-result", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const runId = typeof req.body?.runId === "string" ? req.body.runId : "";
+        const nodeId = typeof req.body?.nodeId === "string" ? req.body.nodeId : "";
+        if (!runId || !nodeId || found.value.planRunId !== runId) {
+            res
+                .status(400)
+                .json({ error: "runId/nodeId do not match the Pipeline plan" });
+            return;
+        }
+        try {
+            workspace.kernel.submitPlanResult(runId, nodeId, req.body?.planResult);
+            res.status(202).json({
+                accepted: true,
+                pipelineRunId: req.params.pipelineRunId,
+                runId,
+                nodeId,
+                nodeCompleted: true,
+                handoffRequired: false,
+            });
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/handoff", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const runId = typeof req.body?.runId === "string" ? req.body.runId : "";
+        const nodeId = typeof req.body?.nodeId === "string" ? req.body.nodeId : "";
+        const outcome = typeof req.body?.outcome === "string" ? req.body.outcome.trim() : "";
+        if (!runId || !nodeId || !outcome) {
+            res
+                .status(400)
+                .json({ error: "runId, nodeId and outcome are required" });
+            return;
+        }
+        try {
+            workspace.kernel.submitHandoff(runId, nodeId, outcome, req.body?.payload);
+            res.status(202).json({
+                accepted: true,
+                pipelineRunId: req.params.pipelineRunId,
+                runId,
+                nodeId,
+            });
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/human-required", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const runId = typeof req.body?.runId === "string" ? req.body.runId : "";
+        const nodeId = typeof req.body?.nodeId === "string" ? req.body.nodeId : "";
+        const title = typeof req.body?.title === "string" ? req.body.title.trim() : "";
+        const instructions = typeof req.body?.instructions === "string"
+            ? req.body.instructions.trim()
+            : "";
+        if (!runId || !nodeId || !title || !instructions) {
+            res.status(400).json({
+                error: "runId, nodeId, title and instructions are required",
+            });
+            return;
+        }
+        try {
+            const created = workspace.kernel.store
+                .events(runId)
+                .find((event) => event.t === "run_created");
+            if (!created ||
+                created.pipelineRunId !== req.params.pipelineRunId ||
+                created.mainAgentId !== req.params.agentId) {
+                res.status(400).json({
+                    error: "runId/nodeId do not match the current Pipeline Node",
+                });
+                return;
+            }
+            const action = HumanInterventionActionSchema.optional().parse(req.body?.action);
+            const request = workspace.kernel.requestHuman(runId, nodeId, {
+                title,
+                instructions,
+                ...(action ? { action } : {}),
+            });
+            res.status(202).json({
+                accepted: true,
+                pipelineRunId: req.params.pipelineRunId,
+                runId,
+                nodeId,
+                request,
+            });
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    router.post("/workspaces/:wid/agents/:agentId/pipelines/:pipelineRunId/human-resolve", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const found = findPipelineRun(workspace, req.params.agentId, req.params.pipelineRunId);
+        if (!found) {
+            res.status(404).json({ error: "PipelineRun not found" });
+            return;
+        }
+        const runId = typeof req.body?.runId === "string" ? req.body.runId : "";
+        const nodeId = typeof req.body?.nodeId === "string" ? req.body.nodeId : "";
+        const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : "";
+        const resolution = req.body?.resolution;
+        const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";
+        if (!runId ||
+            !nodeId ||
+            !requestId ||
+            (resolution !== "continue" && resolution !== "reject")) {
+            res.status(400).json({
+                error: "runId, nodeId, requestId and a valid resolution are required",
+            });
+            return;
+        }
+        try {
+            res.json(found.coordinator.resolveHuman(req.params.pipelineRunId, {
+                runId,
+                nodeId,
+                requestId,
+                resolution,
+                ...(text ? { text } : {}),
+            }));
+        }
+        catch (error) {
+            res.status(409).json({
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    function findPipelineRun(workspace, agentId, pipelineRunId) {
+        for (const [coordinatorKey, coordinator,] of workspace.coordinators.entries()) {
+            // PipelineRunStore is shared by a Workspace, so a Coordinator can see
+            // persisted runs belonging to another Main Agent.  The map key is the
+            // authoritative in-memory owner; do not return an old Agent's
+            // Coordinator merely because its shared store contains this run id.
+            if (!coordinatorKey.startsWith(`${agentId}:`))
+                continue;
+            const value = coordinator.get(pipelineRunId);
+            if (value && value.mainAgentId === agentId)
+                return { coordinator, value };
+        }
+        const bindings = readAgentWorkflowBindings(workspace.rootPath);
+        for (const [boundAgentId, workflowId] of Object.entries(bindings)) {
+            if (boundAgentId !== agentId)
+                continue;
+            try {
+                const coordinator = coordinatorFor(workspace, agentId, workflowId);
+                const value = coordinator.get(pipelineRunId);
+                if (value)
+                    return { coordinator, value };
+            }
+            catch {
+                /* continue to 404 */
+            }
+        }
+        return null;
+    }
+    router.get("/workspaces/:wid/agents/:agentId/tasks", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        res.json(workspace.kernel.tasks
+            .list()
+            .filter((task) => taskBelongsToMainAgent(task, req.params.agentId)));
+    });
+    router.post("/workspaces/:wid/agents/:agentId/tasks", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const { id, title } = req.body ?? {};
+        res.json(workspace.kernel.tasks.add(id, title, undefined, req.params.agentId));
+    });
+    router.get("/workspaces/:wid/runs/:runId", (req, res) => {
+        const workspace = scopedRun(req.params.wid, req.params.runId);
+        if (!workspace) {
+            res.status(404).json({ error: "run not found" });
+            return;
+        }
+        res.json(statusWithRunKind(workspace.kernel.status(req.params.runId), workspace.kernel.store.events(req.params.runId)));
+    });
+    router.get("/workspaces/:wid/runs/:runId/events", (req, res) => {
+        const workspace = scopedRun(req.params.wid, req.params.runId);
+        if (!workspace) {
+            res.status(404).json({ error: "run not found" });
+            return;
+        }
+        const fromOffset = parseInt(req.query.from) || 0;
+        res.json(workspace.kernel.store.readEventsFromOffset(req.params.runId, fromOffset));
+    });
+    for (const [endpoint, method] of [
+        ["interrupt", "interrupt"],
+        ["approve", "approve"],
+        ["reject", "reject"],
+        ["pause", "pause"],
+        ["resume", "resume"],
+        ["goto", "goto"],
+    ]) {
+        router.post(`/workspaces/:wid/runs/:runId/${endpoint}`, (req, res) => {
+            const workspace = scopedRun(req.params.wid, req.params.runId);
+            if (!workspace) {
+                res.status(404).json({ error: "run not found" });
+                return;
+            }
+            const { nodeId, text, feedback } = req.body ?? {};
+            try {
+                if (method === "goto" || method === "interrupt") {
+                    const snapshot = workspace.kernel.status(req.params.runId);
+                    if (snapshot.status === "done" || snapshot.status === "blocked") {
+                        const created = workspace.kernel.store
+                            .events(req.params.runId)
+                            .find((event) => event.t === "run_created");
+                        const ownerAgentId = created?.mainAgentId ?? created?.agentId;
+                        if (!created?.pipelineRunId || !ownerAgentId) {
+                            res.status(409).json({
+                                error: "completed run cannot be reopened without Pipeline scope",
+                            });
+                            return;
+                        }
+                        const found = findPipelineRun(workspace, ownerAgentId, created.pipelineRunId);
+                        if (!found) {
+                            res.status(409).json({
+                                error: "Pipeline coordinator is unavailable for terminal run",
+                            });
+                            return;
+                        }
+                        // Plan Runs are intentionally not Tasks. The planner card in the
+                        // UI uses a synthetic `planner:<PipelineRunId>` id, which must not
+                        // be passed to Execute task-scope recovery. Re-open the original
+                        // Plan Run directly and keep its identity.
+                        if (created.runKind === "plan" ||
+                            (!created.runKind && !created.taskId)) {
+                            if (!nodeId || typeof text !== "string" || !text.trim()) {
+                                res.status(400).json({ error: "nodeId and text are required" });
+                                return;
+                            }
+                            res.json(found.coordinator.reopenPlan(created.pipelineRunId, {
+                                nodeId,
+                                text,
+                            }));
+                            return;
+                        }
+                        if (!created.taskId) {
+                            res.status(409).json({
+                                error: "completed run cannot be reopened without Pipeline task scope",
+                            });
+                            return;
+                        }
+                        if (snapshot.status === "done") {
+                            res.json(found.coordinator.reopenDone(created.pipelineRunId, {
+                                taskId: created.taskId,
+                                nodeId,
+                                text,
+                            }));
+                        }
+                        else {
+                            res.json(found.coordinator.resumeBlocked(created.pipelineRunId, {
+                                taskId: created.taskId,
+                                nodeId,
+                                text,
+                            }));
+                        }
+                        return;
+                    }
+                }
+                switch (method) {
+                    case "interrupt":
+                        workspace.kernel.interrupt(req.params.runId, nodeId, text);
+                        break;
+                    case "approve":
+                        workspace.kernel.approve(req.params.runId, nodeId);
+                        break;
+                    case "reject":
+                        workspace.kernel.reject(req.params.runId, nodeId, feedback);
+                        break;
+                    case "pause":
+                        workspace.kernel.pause(req.params.runId);
+                        break;
+                    case "resume":
+                        workspace.kernel.resume(req.params.runId);
+                        break;
+                    case "goto":
+                        workspace.kernel.goto(req.params.runId, nodeId, text);
+                        break;
+                }
+                res.json({ ok: true });
+            }
+            catch (error) {
+                res.status(500).json({
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+    }
+    router.post("/workspaces/:wid/agents/:agentId/plan", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const { spec: bodySpec, vars, workflowId } = req.body ?? {};
+        let spec = bodySpec;
+        if (!spec && workflowId) {
+            if (typeof workflowId !== "string" || !isSafeWorkflowId(workflowId)) {
+                res.status(400).json({ error: "invalid workflow id" });
+                return;
+            }
+            const fp = workflowPackagePaths(workspace.rootPath, workflowId).workflow;
+            if (fs.existsSync(fp))
+                spec = readJsonFile(fp);
+        }
+        if (!spec) {
+            res.status(400).json({ error: "no spec and no workflow" });
+            return;
+        }
+        const workflowRoot = workflowId
+            ? workflowPackagePaths(workspace.rootPath, workflowId).root
+            : workspace.rootPath;
+        res.json(workspace.kernel.startPlan(spec, vars ?? {}, workflowRoot, req.params.agentId, workspace.workspaceId));
+    });
+    router.post("/workspaces/:wid/agents/:agentId/run", (req, res) => {
+        const workspace = scopedAgent(req.params.wid, req.params.agentId);
+        if (!workspace) {
+            res.status(404).json({ error: "pipeline agent not found" });
+            return;
+        }
+        const workflowId = req.body?.workflowId;
+        if (!workflowId) {
+            res.status(400).json({ error: "no workflowId" });
+            return;
+        }
+        if (!isSafeWorkflowId(workflowId)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const fp = workflowPackagePaths(workspace.rootPath, workflowId).workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        const spec = readJsonFile(fp);
+        const workflowRoot = path.dirname(fp);
+        const runner = new TaskRunner({
+            kernel: workspace.kernel,
+            spec,
+            vars: {},
+            specDir: workflowRoot,
+            pipelineId: req.params.agentId,
+            parentAgentId: req.params.agentId,
+            workspaceId: workspace.workspaceId,
+        });
+        workspace.taskRunners.set(req.params.agentId, runner);
+        runner.start().catch(() => { });
+        res.json({ runnerId: `runner-${Date.now()}`, runIds: [] });
+    });
+    for (const operation of ["pause", "resume"]) {
+        router.post(`/workspaces/:wid/agents/:agentId/pipeline/${operation}`, (req, res) => {
+            const workspace = scopedAgent(req.params.wid, req.params.agentId);
+            if (!workspace) {
+                res.status(404).json({ error: "pipeline agent not found" });
+                return;
+            }
+            if (operation === "pause")
+                workspace.taskRunners.get(req.params.agentId)?.pause();
+            const runIds = [];
+            for (const task of workspace.kernel.tasks
+                .list()
+                .filter((item) => item.agentId === req.params.agentId)) {
+                if (!task.runId)
+                    continue;
+                try {
+                    workspace.kernel[operation](task.runId);
+                    runIds.push(task.runId);
+                }
+                catch {
+                    /* task can point at a stale run */
+                }
+            }
+            res.json({ runIds });
+        });
+    }
+    router.post("/workflows/:id/validate", (req, res) => {
+        const result = safeParseWorkflowSpec(req.body);
+        if (!result.success) {
+            res.status(400).json({ success: false, error: result.error });
+            return;
+        }
+        res.json({ success: true });
+    });
+    // --- Tasks ---
+    router.get("/agents/:agentId/tasks", (req, res) => {
+        const wk = findKernelByAgentId(req.params.agentId);
+        if (!wk) {
+            res.json([]);
+            return;
+        }
+        res.json(wk.kernel.tasks.list().filter((t) => t.agentId === req.params.agentId));
+    });
+    router.post("/agents/:agentId/tasks", (req, res) => {
+        let wk = findKernelByAgentId(req.params.agentId);
+        if (!wk)
+            wk = kernels.get("default");
+        const { id, title } = req.body ?? {};
+        const task = wk.kernel.tasks.add(id, title, undefined, req.params.agentId);
+        res.json(task);
+    });
+    router.post("/agents/:agentId/tasks/import", (req, res) => {
+        let wk = findKernelByAgentId(req.params.agentId);
+        if (!wk)
+            wk = kernels.get("default");
+        const { file } = req.body ?? {};
+        const raw = fs.readFileSync(file, "utf8");
+        const items = parseTaskList(raw);
+        let added = 0, skipped = 0;
+        for (const item of items) {
+            if (wk.kernel.tasks.get(item.id)) {
+                skipped++;
+                continue;
+            }
+            wk.kernel.tasks.add(item.id, item.title, undefined, req.params.agentId);
+            added++;
+        }
+        res.json({ added, skipped });
+    });
+    router.delete("/tasks/:id", (req, res) => {
+        for (const wk of kernels.values()) {
+            if (wk.kernel.tasks.get(req.params.id)) {
+                wk.kernel.tasks.remove(req.params.id);
+                res.json({ ok: true });
+                return;
+            }
+        }
+        res.status(404).json({ error: "task not found" });
+    });
+    router.get("/tasks/:id", (req, res) => {
+        for (const wk of kernels.values()) {
+            const task = wk.kernel.tasks.get(req.params.id);
+            if (task) {
+                const status = wk.kernel.taskStatus(req.params.id);
+                let run = null;
+                if (task.runId) {
+                    try {
+                        run = wk.kernel.status(task.runId);
+                    }
+                    catch { }
+                }
+                res.json({ task, status, run });
+                return;
+            }
+        }
+        res.status(404).json({ error: "task not found" });
+    });
+    router.post("/tasks/:id/runs", (req, res) => {
+        for (const wk of kernels.values()) {
+            const task = wk.kernel.tasks.get(req.params.id);
+            if (task) {
+                const { spec, vars } = req.body ?? {};
+                const { runId } = wk.kernel.startRun(spec, vars ?? {}, wk.rootPath, req.params.id, task.agentId, wk.workspaceId);
+                res.json({ runId });
+                return;
+            }
+        }
+        res.status(404).json({ error: "task not found" });
+    });
+    // --- Runs ---
+    router.get("/runs/:runId", (req, res) => {
+        const wk = findKernelByRunId(req.params.runId);
+        if (!wk) {
+            res.status(404).json({ error: "run not found" });
+            return;
+        }
+        res.json(statusWithRunKind(wk.kernel.status(req.params.runId), wk.kernel.store.events(req.params.runId)));
+    });
+    router.get("/runs/:runId/events", (req, res) => {
+        const wk = findKernelByRunId(req.params.runId);
+        if (!wk) {
+            res.status(404).json({ error: "run not found" });
+            return;
+        }
+        const fromOffset = parseInt(req.query.from) || 0;
+        res.json(wk.kernel.store.readEventsFromOffset(req.params.runId, fromOffset));
+    });
+    // Run commands
+    for (const [ep, method] of [
+        ["interrupt", "interrupt"],
+        ["approve", "approve"],
+        ["reject", "reject"],
+        ["pause", "pause"],
+        ["resume", "resume"],
+        ["goto", "goto"],
+    ]) {
+        router.post(`/runs/:runId/${ep}`, (req, res) => {
+            const wk = findKernelByRunId(req.params.runId);
+            if (!wk) {
+                res.status(404).json({ error: "run not found" });
+                return;
+            }
+            const { nodeId, text, feedback } = req.body ?? {};
+            try {
+                switch (method) {
+                    case "interrupt":
+                        wk.kernel.interrupt(req.params.runId, nodeId, text);
+                        break;
+                    case "approve":
+                        wk.kernel.approve(req.params.runId, nodeId);
+                        break;
+                    case "reject":
+                        wk.kernel.reject(req.params.runId, nodeId, feedback);
+                        break;
+                    case "pause":
+                        wk.kernel.pause(req.params.runId);
+                        break;
+                    case "resume":
+                        wk.kernel.resume(req.params.runId);
+                        break;
+                    case "goto":
+                        wk.kernel.goto(req.params.runId, nodeId, text);
+                        break;
+                }
+                res.json({ ok: true });
+            }
+            catch (e) {
+                res
+                    .status(500)
+                    .json({ error: e instanceof Error ? e.message : String(e) });
+            }
+        });
+    }
+    // --- Pipeline control ---
+    router.post("/agents/:agentId/plan", (req, res) => {
+        let wk = findKernelByAgentId(req.params.agentId);
+        if (!wk)
+            wk = kernels.get("default");
+        const { spec: bodySpec, vars, workflowId } = req.body ?? {};
+        let spec = bodySpec;
+        if (!spec && workflowId) {
+            if (typeof workflowId !== "string" || !isSafeWorkflowId(workflowId)) {
+                res.status(400).json({ error: "invalid workflow id" });
+                return;
+            }
+            const fp = workflowPackagePaths(wk.rootPath, workflowId).workflow;
+            if (fs.existsSync(fp)) {
+                spec = readJsonFile(fp);
+            }
+        }
+        if (!spec) {
+            res.status(400).json({ error: "no spec and no workflow" });
+            return;
+        }
+        const workflowRoot = workflowId
+            ? workflowPackagePaths(wk.rootPath, workflowId).root
+            : wk.rootPath;
+        const { runId } = wk.kernel.startPlan(spec, vars ?? {}, workflowRoot, req.params.agentId, wk.workspaceId);
+        res.json({ runId });
+    });
+    router.post("/agents/:agentId/run", (req, res) => {
+        let wk = findKernelByAgentId(req.params.agentId);
+        if (!wk)
+            wk = kernels.get("default");
+        const wfId = req.body?.workflowId;
+        if (!wfId) {
+            res.status(400).json({ error: "no workflowId" });
+            return;
+        }
+        if (!isSafeWorkflowId(wfId)) {
+            res.status(400).json({ error: "invalid workflow id" });
+            return;
+        }
+        const fp = workflowPackagePaths(wk.rootPath, wfId).workflow;
+        if (!fs.existsSync(fp)) {
+            res.status(404).json({ error: "workflow not found" });
+            return;
+        }
+        const spec = readJsonFile(fp);
+        const runner = new TaskRunner({
+            kernel: wk.kernel,
+            spec,
+            vars: {},
+            specDir: path.dirname(fp),
+            pipelineId: req.params.agentId,
+            parentAgentId: req.params.agentId,
+            workspaceId: wk.workspaceId,
+        });
+        wk.taskRunners.set(req.params.agentId, runner);
+        runner.start().catch(() => { });
+        res.json({ runnerId: `runner-${Date.now()}`, runIds: [] });
+    });
+    router.post("/agents/:agentId/pipeline/pause", (req, res) => {
+        let wk = findKernelByAgentId(req.params.agentId);
+        if (!wk)
+            wk = kernels.get("default");
+        const runner = wk.taskRunners.get(req.params.agentId);
+        if (runner)
+            runner.pause();
+        const tasks = wk.kernel.tasks
+            .list()
+            .filter((t) => t.agentId === req.params.agentId);
+        const runIds = [];
+        for (const t of tasks) {
+            if (t.runId) {
+                try {
+                    wk.kernel.pause(t.runId);
+                    runIds.push(t.runId);
+                }
+                catch { }
+            }
+        }
+        res.json({ runIds });
+    });
+    router.post("/agents/:agentId/pipeline/resume", (req, res) => {
+        let wk = findKernelByAgentId(req.params.agentId);
+        if (!wk)
+            wk = kernels.get("default");
+        const tasks = wk.kernel.tasks
+            .list()
+            .filter((t) => t.agentId === req.params.agentId);
+        const runIds = [];
+        for (const t of tasks) {
+            if (t.runId) {
+                try {
+                    wk.kernel.resume(t.runId);
+                    runIds.push(t.runId);
+                }
+                catch { }
+            }
+        }
+        res.json({ runIds });
+    });
+    return {
+        serverId,
+        async request(pathname, options = {}) {
+            const url = new URL(pathname, "http://agentstorm.internal");
+            const routePath = url.pathname.startsWith("/api/")
+                ? url.pathname.slice("/api".length)
+                : url.pathname;
+            const result = await router.dispatch({
+                method: options.method ?? "GET",
+                pathname: routePath,
+                query: url.searchParams,
+                body: options.body,
+                ...(options.etag ? { headers: { "if-match": options.etag } } : {}),
+            });
+            if (result.status >= 400) {
+                throw new PipelineServiceRequestError(result.status, result.body);
+            }
+            return result.body;
+        },
+        readEventsFromOffset(runId, offset) {
+            for (const wk of kernels.values()) {
+                for (const runtime of [wk, ...wk.sessions.values()]) {
+                    const result = runtime.kernel.store.readEventsFromOffset(runId, offset);
+                    if (result.nextOffset !== offset || result.events.length > 0)
+                        return result;
+                }
+            }
+            return { events: [], nextOffset: offset };
+        },
+        async close() { },
+    };
+}
+export class PipelineServiceRequestError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Pipeline service ${status}: ${JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+class PipelineRouteRegistry {
+    routes = [];
+    get(template, handler) {
+        this.add("GET", template, handler);
+    }
+    post(template, handler) {
+        this.add("POST", template, handler);
+    }
+    put(template, handler) {
+        this.add("PUT", template, handler);
+    }
+    delete(template, handler) {
+        this.add("DELETE", template, handler);
+    }
+    async dispatch(input) {
+        for (const route of this.routes) {
+            if (route.method !== input.method)
+                continue;
+            const params = matchPipelineRoute(route.template, input.pathname);
+            if (!params)
+                continue;
+            return invokePipelineRoute(route.handler, params, input);
+        }
+        return { status: 404, body: { error: "Pipeline route not found" } };
+    }
+    add(method, template, handler) {
+        this.routes.push({ method, template, handler: handler });
+    }
+}
+async function invokePipelineRoute(handler, params, input) {
+    let status = 200;
+    let body;
+    let responded = false;
+    const headers = Object.fromEntries(Object.entries(input.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
+    const request = {
+        params,
+        body: input.body,
+        query: Object.fromEntries(input.query.entries()),
+        headers,
+        header(name) {
+            return headers[name.toLowerCase()];
+        },
+    };
+    const response = {
+        status(code) {
+            status = code;
+            return response;
+        },
+        json(value) {
+            body = value;
+            responded = true;
+            return response;
+        },
+    };
+    await handler(request, response, () => undefined);
+    if (!responded)
+        throw new Error(`Pipeline route ${input.method} ${input.pathname} did not respond`);
+    return { status, body };
+}
+function matchPipelineRoute(template, pathname) {
+    const templateParts = template.split("/").filter(Boolean);
+    const pathParts = pathname.split("/").filter(Boolean);
+    if (templateParts.length !== pathParts.length)
+        return null;
+    const params = {};
+    for (const [index, templatePart] of templateParts.entries()) {
+        const pathPart = pathParts[index];
+        if (templatePart.startsWith(":")) {
+            params[templatePart.slice(1)] = decodeURIComponent(pathPart);
+        }
+        else if (templatePart !== pathPart) {
+            return null;
+        }
+    }
+    return params;
+}
+function etagOf(raw) {
+    // Package writes append one final newline; callers that just serialised the
+    // same JSON may not. Treat that formatting difference as the same document
+    // so a freshly-created Workflow can be updated with the returned ETag.
+    const canonical = raw.replace(/\r?\n$/, "");
+    return `"${createHash("sha256")
+        .update(canonical)
+        .digest("hex")
+        .slice(0, 16)}"`;
+}
+function isSafeWorkflowId(value) {
+    // Workflow names are user-facing, so Unicode and spaces are deliberately
+    // allowed. Only reject strings that could make the JSON file escape its
+    // workspace-local .agentstorm/workflows directory.
+    return (value.length > 0 &&
+        value !== "." &&
+        value !== ".." &&
+        !/[\\/\0]/.test(value));
+}
+/** Read-only compatibility for Workflow files written before Prompt and
+ * Skills moved from graph nodes to the Agent registry. New saves never emit
+ * these node fields, but old packages remain runnable while they migrate. */
+function legacyAgentNode(spec, agentId) {
+    for (const graph of [spec.plan, spec.execute]) {
+        const node = graph?.nodes.find((candidate) => candidate.type !== "approval" && candidate.agent === agentId);
+        if (node)
+            return node;
+    }
+    return undefined;
+}
+function effectiveAgentPrompt(spec, agentId, config) {
+    return config.prompt ?? legacyAgentNode(spec, agentId)?.prompt;
+}
+function effectiveAgentSkills(spec, agentId, config) {
+    if (config.skills !== undefined)
+        return config.skills;
+    return legacyAgentNode(spec, agentId)?.skills ?? [];
+}
+function rewriteBundlePromptRefs(spec, assets) {
+    const assetNames = new Set(assets);
+    const agents = Object.fromEntries(Object.entries(spec.agents).map(([agentId, config]) => {
+        const prompt = effectiveAgentPrompt(spec, agentId, config);
+        if (!prompt?.startsWith("@"))
+            return [agentId, config];
+        const reference = prompt.slice(1).replaceAll("\\", "/");
+        if (!reference.startsWith("prompts/") || !assetNames.has(reference)) {
+            throw new Error(`Workflow Bundle 的 Prompt 必须引用 prompts/<Agent ID>.md：${reference}`);
+        }
+        return [agentId, { ...config, prompt: `@${reference}` }];
+    }));
+    return {
+        ...spec,
+        agents,
+    };
+}
+function ensureWorkflowPromptFiles(packageRoot, spec) {
+    validateWorkflowPromptReferences(spec);
+    for (const [agentId, config] of Object.entries(spec.agents)) {
+        const prompt = effectiveAgentPrompt(spec, agentId, config);
+        if (!prompt?.startsWith("@"))
+            continue;
+        const reference = prompt.slice(1).replaceAll("\\", "/");
+        const safe = safePackageRelativePath(reference);
+        if (!safe)
+            throw new Error(`Prompt 路径无效：${reference}`); // validated above
+        const target = path.resolve(packageRoot, safe);
+        assertInsidePackage(packageRoot, target);
+        if (!fs.existsSync(target)) {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, "# Agent instructions\n\n根据当前任务描述完成工作，并记录可复核的结果。\n", "utf8");
+        }
+    }
+}
+function validateWorkflowPromptReferences(spec) {
+    for (const [agentId, config] of Object.entries(spec.agents)) {
+        const prompt = effectiveAgentPrompt(spec, agentId, config);
+        if (!prompt?.startsWith("@prompts/"))
+            continue;
+        const reference = prompt.slice(1).replaceAll("\\", "/");
+        const safe = safePackageRelativePath(reference);
+        if (!safe)
+            throw new Error(`Prompt 路径无效：${reference}`);
+        const expected = workflowPromptRelativePath(agentId).replaceAll("\\", "/");
+        if (reference !== expected) {
+            throw new Error(`Prompt 文件必须与 Agent ID 绑定：${agentId} → @${expected}`);
+        }
+    }
+}
+function collectPromptAssets(rootPath, spec) {
+    const assets = {};
+    for (const [agentId, config] of Object.entries(spec.agents)) {
+        const prompt = effectiveAgentPrompt(spec, agentId, config);
+        if (!prompt?.startsWith("@"))
+            continue;
+        const reference = prompt.slice(1).replaceAll("\\", "/");
+        const safe = safePackageRelativePath(reference);
+        if (!safe)
+            throw new Error(`prompt asset escapes Workspace: ${reference}`);
+        const target = path.resolve(rootPath, safe);
+        const root = path.resolve(rootPath);
+        if (target !== root && !target.startsWith(`${root}${path.sep}`))
+            throw new Error(`prompt asset escapes Workspace: ${reference}`);
+        if (!fs.existsSync(target) || !fs.statSync(target).isFile())
+            throw new Error(`prompt asset not found: ${reference}`);
+        assets[reference] = fs.readFileSync(target, "utf8");
+    }
+    return assets;
+}
+/**
+ * Check the parts of a Workflow that AgentStorm can prove before spawning a
+ * Paseo Agent. Provider/model resolution remains delegated to the Paseo
+ * daemon's live provider snapshot; this check deliberately reports the
+ * configured values rather than pretending PipelineService owns that registry.
+ */
+export function workflowReadiness(rootPath, spec) {
+    const missingPromptAssets = [];
+    const missingSkills = [];
+    const root = path.resolve(rootPath);
+    for (const [agentId, config] of Object.entries(spec.agents)) {
+        const prompt = effectiveAgentPrompt(spec, agentId, config);
+        if (prompt?.startsWith("@")) {
+            const reference = prompt.slice(1).replaceAll("\\", "/");
+            const safe = safePackageRelativePath(reference);
+            const expected = workflowPromptRelativePath(agentId).replaceAll("\\", "/");
+            if (!safe ||
+                !reference.startsWith("prompts/") ||
+                reference !== expected) {
+                missingPromptAssets.push({
+                    agentId,
+                    reference,
+                    reason: "outside_workspace",
+                });
+            }
+            else {
+                const target = path.resolve(root, safe);
+                if (target !== root && !target.startsWith(`${root}${path.sep}`)) {
+                    missingPromptAssets.push({
+                        agentId,
+                        reference,
+                        reason: "outside_workspace",
+                    });
+                }
+                else {
+                    try {
+                        if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+                            missingPromptAssets.push({
+                                agentId,
+                                reference,
+                                reason: "not_found",
+                            });
+                            continue;
+                        }
+                        const realRoot = fs.realpathSync(root);
+                        const realTarget = fs.realpathSync(target);
+                        if (realTarget !== realRoot &&
+                            !realTarget.startsWith(`${realRoot}${path.sep}`)) {
+                            missingPromptAssets.push({
+                                agentId,
+                                reference,
+                                reason: "outside_workspace",
+                            });
+                        }
+                    }
+                    catch {
+                        missingPromptAssets.push({
+                            agentId,
+                            reference,
+                            reason: "not_found",
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const agents = Object.entries(spec.agents).map(([agentId, config]) => ({
+        agentId,
+        provider: config.provider,
+        model: config.model,
+        status: "configured",
+    }));
+    return {
+        ready: missingPromptAssets.length === 0 && missingSkills.length === 0,
+        errors: [],
+        missingPromptAssets,
+        missingSkills,
+        agents,
+    };
+}
+export async function workflowReadinessWithBackend(rootPath, spec, backend, skillCwd = rootPath) {
+    const skillsByAgent = new Map();
+    const errors = [];
+    const agentsWithSkills = new Set();
+    for (const [agentId, config] of Object.entries(spec.agents)) {
+        if (effectiveAgentSkills(spec, agentId, config).length > 0)
+            agentsWithSkills.add(agentId);
+    }
+    for (const agentId of agentsWithSkills) {
+        const config = spec.agents[agentId];
+        if (!config) {
+            skillsByAgent.set(agentId, new Set());
+            continue;
+        }
+        if (!backend.listSkills) {
+            errors.push(agentId +
+                " (" +
+                config.provider +
+                ") Skill 能力不可用：当前 AgentRuntime 未提供 Provider Skill 列表");
+            skillsByAgent.set(agentId, new Set());
+            continue;
+        }
+        try {
+            const skills = await backend.listSkills({
+                provider: config.provider,
+                model: config.model,
+                // Prompt assets live inside the Workflow package, while Provider
+                // skills are discovered from the Workspace (and its provider-specific
+                // .<provider>/ directories). These roots are intentionally distinct.
+                cwd: skillCwd,
+                ...(config.mode ? { mode: config.mode } : {}),
+                ...(config.thinking ? { thinking: config.thinking } : {}),
+            });
+            skillsByAgent.set(agentId, new Set(skills.map((skill) => skill.name)));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${agentId} (${config.provider}) Skill 能力不可用：${message}`);
+            skillsByAgent.set(agentId, new Set());
+        }
+    }
+    const readiness = workflowReadiness(rootPath, spec);
+    const missingSkills = Object.entries(spec.agents).flatMap(([agentId, config]) => {
+        const available = skillsByAgent.get(agentId);
+        return effectiveAgentSkills(spec, agentId, config)
+            .filter((skill) => available === undefined || !available.has(skill))
+            .map((skill) => ({ agentId, skill }));
+    });
+    return {
+        ...readiness,
+        errors: [...readiness.errors, ...errors],
+        missingSkills,
+        ready: readiness.ready && errors.length === 0 && missingSkills.length === 0,
+    };
+}
+function isSafeWorkspaceRelativePath(value) {
+    const normalized = value.replaceAll("\\", "/");
+    if (!normalized ||
+        normalized.startsWith("/") ||
+        /^[A-Za-z]:\//.test(normalized))
+        return false;
+    return normalized
+        .split("/")
+        .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+/** Workspace-local session → selected Workflow mapping. This lives outside
+ * `workflows/` so it cannot be mistaken for a Workflow document by list or
+ * versioning APIs. */
+function agentWorkflowBindingsPath(rootPath) {
+    return path.join(rootPath, ".agentstorm", "agent-workflows.json");
+}
+function readLegacyAgentWorkflowBindings(rootPath) {
+    const bindingsPath = agentWorkflowBindingsPath(rootPath);
+    if (!fs.existsSync(bindingsPath))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(bindingsPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === "string" && isSafeWorkflowId(entry[1])));
+    }
+    catch {
+        return {};
+    }
+}
+function sessionPathSegment(agentId) {
+    return encodeURIComponent(agentId).replace(/[.']/g, (char) => char === "." ? "%2E" : "%27");
+}
+function sessionWorkflowFiles(rootPath) {
+    const sessionsRoot = path.join(rootPath, ".agentstorm", "sessions");
+    if (!fs.existsSync(sessionsRoot))
+        return [];
+    return fs
+        .readdirSync(sessionsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(sessionsRoot, entry.name, "session.json"))
+        .filter((file) => fs.existsSync(file));
+}
+function readSessionRecord(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSessionWorkflowBindings(rootPath) {
+    const files = sessionWorkflowFiles(rootPath);
+    if (files.length === 0)
+        return null;
+    const bindings = {};
+    for (const file of files) {
+        const record = readSessionRecord(file);
+        if (record &&
+            typeof record.mainAgentId === "string" &&
+            typeof record.workflowId === "string" &&
+            isSafeWorkflowId(record.workflowId)) {
+            bindings[record.mainAgentId] = record.workflowId;
+        }
+    }
+    return bindings;
+}
+function readAgentWorkflowBindings(rootPath) {
+    const sessionBindings = readSessionWorkflowBindings(rootPath);
+    if (sessionBindings !== null)
+        return sessionBindings;
+    const bindingsPath = agentWorkflowBindingsPath(rootPath);
+    if (!fs.existsSync(bindingsPath))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(bindingsPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const bindings = {};
+        for (const [agentId, workflowId] of Object.entries(parsed)) {
+            if (typeof workflowId === "string" && isSafeWorkflowId(workflowId)) {
+                bindings[agentId] = workflowId;
+            }
+        }
+        return bindings;
+    }
+    catch {
+        // A bad local preference must not make stored Workflows inaccessible.
+        return {};
+    }
+}
+function writeAgentWorkflowBinding(rootPath, agentId, workflowId) {
+    const sessionsRoot = path.join(rootPath, ".agentstorm", "sessions");
+    fs.mkdirSync(path.join(sessionsRoot, sessionPathSegment(agentId)), {
+        recursive: true,
+    });
+    const file = path.join(sessionsRoot, sessionPathSegment(agentId), "session.json");
+    let current = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            current = parsed;
+    }
+    catch {
+        /* first binding */
+    }
+    writeSessionJsonAtomic(file, {
+        ...current,
+        sessionId: typeof current.sessionId === "string" ? current.sessionId : agentId,
+        mainAgentId: agentId,
+        workflowId,
+        updatedAt: nowBeijing(),
+    });
+}
+function clearAgentWorkflowBindings(rootPath, workflowId) {
+    const sessionFiles = sessionWorkflowFiles(rootPath);
+    if (sessionFiles.length > 0) {
+        const cleared = [];
+        for (const file of sessionFiles) {
+            const record = readSessionRecord(file);
+            if (!record || record.workflowId !== workflowId)
+                continue;
+            delete record.workflowId;
+            record.updatedAt = nowBeijing();
+            writeSessionJsonAtomic(file, record);
+            if (typeof record.mainAgentId === "string")
+                cleared.push(record.mainAgentId);
+        }
+        return cleared;
+    }
+    const bindingsPath = agentWorkflowBindingsPath(rootPath);
+    const current = readAgentWorkflowBindings(rootPath);
+    const clearedAgentIds = Object.entries(current)
+        .filter(([, boundWorkflowId]) => boundWorkflowId === workflowId)
+        .map(([agentId]) => agentId);
+    if (clearedAgentIds.length === 0)
+        return [];
+    const next = Object.fromEntries(Object.entries(current).filter(([, boundWorkflowId]) => boundWorkflowId !== workflowId));
+    if (Object.keys(next).length === 0) {
+        fs.rmSync(bindingsPath, { force: true });
+        return clearedAgentIds;
+    }
+    const tmp = `${bindingsPath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2), "utf8");
+    fs.renameSync(tmp, bindingsPath);
+    return clearedAgentIds;
+}
+function renameAgentWorkflowBindings(rootPath, oldWorkflowId, newWorkflowId) {
+    const sessionFiles = sessionWorkflowFiles(rootPath);
+    if (sessionFiles.length > 0) {
+        for (const file of sessionFiles) {
+            const record = readSessionRecord(file);
+            if (!record || record.workflowId !== oldWorkflowId)
+                continue;
+            record.workflowId = newWorkflowId;
+            record.updatedAt = nowBeijing();
+            writeSessionJsonAtomic(file, record);
+        }
+        return;
+    }
+    const bindingsPath = agentWorkflowBindingsPath(rootPath);
+    const current = readAgentWorkflowBindings(rootPath);
+    let changed = false;
+    const next = Object.fromEntries(Object.entries(current).map(([agentId, workflowId]) => {
+        if (workflowId !== oldWorkflowId)
+            return [agentId, workflowId];
+        changed = true;
+        return [agentId, newWorkflowId];
+    }));
+    if (!changed)
+        return;
+    const tmp = `${bindingsPath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2), "utf8");
+    fs.renameSync(tmp, bindingsPath);
+}
+function workflowVersionNumbers(files) {
+    const dir = files.versions;
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .flatMap((file) => {
+        const match = /^(\d+)\.json$/.exec(file);
+        return match ? [Number(match[1])] : [];
+    })
+        .filter((version) => Number.isSafeInteger(version) && version > 0)
+        .sort((a, b) => a - b);
+}
+function readWorkflowVersion(files, version) {
+    if (!Number.isSafeInteger(version) || version < 1)
+        return null;
+    const fp = path.join(files.versions, `${version}.json`);
+    return fs.existsSync(fp) ? fs.readFileSync(fp, "utf8") : null;
+}
+function listWorkflowVersions(files, currentRaw) {
+    const versions = workflowVersionNumbers(files).flatMap((version) => {
+        const raw = readWorkflowVersion(files, version);
+        if (!raw)
+            return [];
+        const fp = path.join(files.versions, `${version}.json`);
+        return [
+            {
+                version,
+                spec: JSON.parse(raw),
+                etag: etagOf(raw),
+                updatedAt: toBeijingIso(fs.statSync(fp).mtime),
+            },
+        ];
+    });
+    // Workflows written before versioning remains readable and restorable as a
+    // synthetic v0 until their next save materializes a durable snapshot.
+    if (versions.length === 0) {
+        return [
+            {
+                version: 0,
+                spec: JSON.parse(currentRaw),
+                etag: etagOf(currentRaw),
+                updatedAt: nowBeijing(),
+            },
+        ];
+    }
+    return versions;
+}
+//# sourceMappingURL=pipeline-service.js.map