cool-workflow 0.1.78

package/dist/verifier-registry.js

@@ -0,0 +1,46 @@
+"use strict";
+// Verifier Registry — open pluggability for commit-gate verifiers.
+//
+// BSD discipline (mechanism separate from policy):
+//  - MECHANISM: a Map<string, Verifier> with register + resolve.
+//  - POLICY: which verifiers exist is declared via registerVerifier() at load time.
+//  - FAIL CLOSED: unknown verifier id → named refusal.
+//  - COMPOSABLE: multiple verifiers can be chained; each runs in registration order.
+//
+// From v0.1.58: the built-in verifier (validateResultEnvelope, validateRunGates,
+// hasGroundedEvidence) remains the default. Registered verifiers run BEFORE the
+// default — they can block or add evidence but cannot override the default gate.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerVerifier = registerVerifier;
+exports.getVerifier = getVerifier;
+exports.listVerifiers = listVerifiers;
+exports.runAllVerifiers = runAllVerifiers;
+const _verifierRegistry = new Map();
+function registerVerifier(verifier) {
+    _verifierRegistry.set(verifier.id, verifier);
+}
+function getVerifier(id) {
+    return _verifierRegistry.get(id);
+}
+function listVerifiers() {
+    return [..._verifierRegistry.values()];
+}
+/** Run all registered verifiers against a run. Returns the aggregated verdict:
+ *  "pass" if all pass, "block" if any block (first block reason wins). */
+async function runAllVerifiers(input) {
+    const reasons = [];
+    const evidence = [];
+    for (const verifier of _verifierRegistry.values()) {
+        const result = await verifier.verify(input);
+        if (result.evidence)
+            evidence.push(...result.evidence);
+        if (result.verdict === "block") {
+            reasons.push(`[${verifier.id}] ${result.reason || "blocked by verifier"}`);
+        }
+        else if (result.verdict === "warn") {
+            reasons.push(`[${verifier.id}] warn: ${result.reason || "warning"}`);
+        }
+    }
+    const blocked = reasons.some((r) => !r.includes("warn:"));
+    return { verdict: blocked ? "block" : "pass", reasons, evidence };
+}

package/dist/verifier.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertTaskCanComplete = assertTaskCanComplete;
+exports.parseResultEnvelope = parseResultEnvelope;
+exports.taskRequiresEvidence = taskRequiresEvidence;
+exports.validateResultEnvelope = validateResultEnvelope;
+exports.validateRunGates = validateRunGates;
+const dispatch_1 = require("./dispatch");
+const evidence_grounding_1 = require("./evidence-grounding");
+const result_normalize_1 = require("./result-normalize");
+const schema_validate_1 = require("./schema-validate");
+function assertTaskCanComplete(run, task) {
+    const runnablePhase = (0, dispatch_1.firstRunnablePhase)(run);
+    if (!runnablePhase || runnablePhase.name !== task.phase) {
+        throw new Error(`Phase gate blocked task ${task.id}; current runnable phase is ${runnablePhase?.name || "none"}`);
+    }
+    if (!["pending", "running"].includes(task.status)) {
+        throw new Error(`Task ${task.id} cannot be completed from status ${task.status}`);
+    }
+}
+// Ingest is delegated to the robust normalizer (v0.1.42): canonical
+// `{summary, findings, evidence}` passes through unchanged, but when the agent
+// uses its own shape (or prose) CW extracts findings from alternative keys and
+// DERIVES grounded evidence itself rather than capturing nothing.
+function parseResultEnvelope(markdown) {
+    return (0, result_normalize_1.normalizeResultEnvelope)(markdown);
+}
+/** Whether a task's result MUST carry evidence (verify/verdict/synthesis tasks
+ *  and any task that opted in via requiresEvidence). The commit gate reuses this
+ *  so its evidence-grounding check matches the acceptance-time policy exactly. */
+function taskRequiresEvidence(task) {
+    return Boolean(task.requiresEvidence ||
+        /^verify[:/]/i.test(task.id) ||
+        /^verdict[:/]/i.test(task.id) ||
+        /^synthesis[:/]/i.test(task.id));
+}
+function validateResultEnvelope(task, result) {
+    const mustHaveEvidence = taskRequiresEvidence(task);
+    if (mustHaveEvidence && !(0, evidence_grounding_1.hasGroundedEvidence)(result.evidence)) {
+        throw new Error(`Task ${task.id} requires grounded cw:result evidence (a path-like locator, URL, or namespace:value token — not free text)`);
+    }
+    for (const finding of result.findings || []) {
+        validateFinding(task, finding);
+    }
+    // Track 3: if the task declared an output schema, the accepted result envelope
+    // must conform. Fail-closed (throw ⇒ the drive parks the hop), consistent with
+    // the checks above. No schema declared ⇒ no check (opt-in by declaration).
+    if (task.schema) {
+        const violations = (0, schema_validate_1.validateAgainstSchema)(result, task.schema);
+        if (violations.length) {
+            throw new Error(`Task ${task.id} result violates declared schema: ${violations.slice(0, 5).join("; ")}${violations.length > 5 ? ` (+${violations.length - 5} more)` : ""}`);
+        }
+    }
+}
+function validateRunGates(run) {
+    const verdictTasks = run.tasks.filter((task) => /^verdict[:/]|^synthesis[:/]/i.test(task.id));
+    for (const verdictTask of verdictTasks) {
+        if (verdictTask.status !== "completed")
+            continue;
+        const verdictPhaseIndex = run.phases.findIndex((phase) => phase.name === verdictTask.phase);
+        const earlierPhases = run.phases.slice(0, verdictPhaseIndex);
+        const incompleteEarlier = earlierPhases.find((phase) => phase.status !== "completed");
+        if (incompleteEarlier) {
+            throw new Error(`Verdict gate blocked ${verdictTask.id}; phase ${incompleteEarlier.name} is not complete`);
+        }
+    }
+}
+function validateFinding(task, finding) {
+    if (!finding.id)
+        throw new Error(`Task ${task.id} has a finding without id`);
+    if (finding.classification &&
+        !["real", "conditional", "non-issue", "unknown"].includes(finding.classification)) {
+        throw new Error(`Task ${task.id} finding ${finding.id} has invalid classification`);
+    }
+    if (["P0", "P1", "P2"].includes(finding.severity || "") && !(0, evidence_grounding_1.hasGroundedEvidence)(finding.evidence)) {
+        throw new Error(`Task ${task.id} finding ${finding.id} severity ${finding.severity} requires grounded evidence (a path-like locator, URL, or namespace:value token)`);
+    }
+}

package/dist/version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.78";
+exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
+exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
+exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;
+exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/workbench-host.js

@@ -0,0 +1,172 @@
+"use strict";
+// Web / Desktop Workbench host (v0.1.30) — a thin, OPTIONAL localhost renderer.
+//
+// BSD discipline:
+//  - LEAST PRIVILEGE, LOCAL BY DEFAULT. Binds 127.0.0.1 ONLY, serves read-only
+//    derived views, exposes nothing beyond the current user's `.cw/` scope and
+//    the v0.1.28 registry's registered repos. It also rejects non-localhost Host
+//    headers (DNS-rebinding defense) and fails closed on anything it cannot read.
+//  - READ-ONLY BY DEFAULT. Every route is GET; any write verb is refused 405.
+//    The host offers no actions — it is pure inspection. (A future action would
+//    have to route through a declared capability core entry, never a parallel
+//    path, so it stays parity-gated.)
+//  - NO HIDDEN DASHBOARD / OPTIONAL SURFACE. The host imports the kernel, never
+//    the reverse. It holds zero authoritative state: every response is re-derived
+//    on demand from disk via the SAME core entries the CLI/MCP use. The committed
+//    `dist/` + plain `node` runtime keep working with this file deleted.
+//
+// See src/workbench.ts and docs/web-desktop-workbench.7.md.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkbenchHost = void 0;
+const node_http_1 = __importDefault(require("node:http"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const workbench_1 = require("./workbench");
+const ALLOWED_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml"
+};
+class WorkbenchHost {
+    runner;
+    cwd;
+    port;
+    scope;
+    host = "127.0.0.1";
+    server;
+    constructor(options) {
+        this.runner = options.runner;
+        this.cwd = node_path_1.default.resolve(String(options.cwd || process.cwd()));
+        this.port = options.port && options.port > 0 ? Math.floor(options.port) : workbench_1.WORKBENCH_DEFAULT_PORT;
+        this.scope = options.scope === "repo" ? "repo" : "home";
+    }
+    /** The canonical serve descriptor — identical to `cw workbench serve --json`. */
+    descriptor(once) {
+        return (0, workbench_1.buildWorkbenchServeDescriptor)(this.runner, { cwd: this.cwd, port: this.port, scope: this.scope, once });
+    }
+    /** Start listening on loopback only. Resolves with the actually-bound port
+     *  (an ephemeral 0 becomes a real port — useful for tests). */
+    listen() {
+        const server = node_http_1.default.createServer((req, res) => this.handle(req, res));
+        this.server = server;
+        return new Promise((resolve, reject) => {
+            server.once("error", reject);
+            // Bind the loopback interface ONLY — never a public address.
+            server.listen(this.port, this.host, () => {
+                const address = server.address();
+                const port = address && typeof address === "object" ? address.port : this.port;
+                resolve({ host: this.host, port });
+            });
+        });
+    }
+    close() {
+        return new Promise((resolve) => {
+            if (!this.server)
+                return resolve();
+            this.server.close(() => resolve());
+        });
+    }
+    /** Run until interrupted (the CLI default `workbench serve`). */
+    async run() {
+        const bound = await this.listen();
+        process.stdout.write(`${JSON.stringify({ ...this.descriptor(false), boundPort: bound.port })}\n`);
+    }
+    handle(req, res) {
+        try {
+            // Fail closed on anything but a localhost GET.
+            if (!isLocalHost(req.headers.host))
+                return this.send(res, 403, { error: "forbidden: non-localhost Host header" });
+            if ((req.method || "GET").toUpperCase() !== "GET") {
+                return this.send(res, 405, { error: "read-only: only GET is permitted" }, { Allow: "GET" });
+            }
+            const url = new URL(req.url || "/", `http://${this.host}`);
+            const route = decodeURIComponent(url.pathname);
+            if (route === "/" || route === "/index.html")
+                return this.sendAsset(res, "index.html");
+            if (route.startsWith("/ui/"))
+                return this.sendAsset(res, route.slice("/ui/".length));
+            if (route === "/api/serve")
+                return this.send(res, 200, this.descriptor(true));
+            if (route === "/api/index") {
+                const args = Object.fromEntries(url.searchParams.entries());
+                return this.send(res, 200, (0, workbench_1.buildWorkbenchIndex)(this.runner, { cwd: this.cwd, scope: this.scope, ...args }));
+            }
+            const runMatch = /^\/api\/run\/([^/]+)$/.exec(route);
+            if (runMatch) {
+                const previousCwd = process.cwd();
+                process.chdir(this.cwd);
+                try {
+                    return this.send(res, 200, (0, workbench_1.buildWorkbenchRunView)(this.runner, runMatch[1]));
+                }
+                finally {
+                    process.chdir(previousCwd);
+                }
+            }
+            this.send(res, 404, { error: `no such read-only view: ${route}` });
+        }
+        catch (error) {
+            this.send(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /** Serve a static UI asset from disk, re-read on every request (no caching of
+     *  authoritative state). Path-traversal is refused; a missing asset is an
+     *  honest 404 — the framework ships fine without the UI installed. */
+    sendAsset(res, relative) {
+        const uiRoot = (0, workbench_1.workbenchUiRoot)(this.runner);
+        const resolved = node_path_1.default.resolve(uiRoot, relative);
+        if (resolved !== uiRoot && !resolved.startsWith(uiRoot + node_path_1.default.sep)) {
+            return this.send(res, 403, { error: "forbidden: path traversal" });
+        }
+        let body;
+        try {
+            body = node_fs_1.default.readFileSync(resolved);
+        }
+        catch {
+            if (relative === "index.html") {
+                return this.sendRaw(res, 200, CONTENT_TYPES[".html"], Buffer.from(FALLBACK_HTML(uiRoot)));
+            }
+            return this.send(res, 404, { error: `UI asset not installed: ${relative}` });
+        }
+        this.sendRaw(res, 200, CONTENT_TYPES[node_path_1.default.extname(resolved)] || "application/octet-stream", body);
+    }
+    send(res, status, body, headers = {}) {
+        this.sendRaw(res, status, CONTENT_TYPES[".json"], Buffer.from(JSON.stringify(body, null, 2)), headers);
+    }
+    sendRaw(res, status, contentType, body, headers = {}) {
+        res.writeHead(status, {
+            "Content-Type": contentType,
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+            ...headers
+        });
+        res.end(body);
+    }
+}
+exports.WorkbenchHost = WorkbenchHost;
+function isLocalHost(hostHeader) {
+    if (!hostHeader)
+        return true; // HTTP/1.0 / no Host — loopback bind already constrains us.
+    const hostname = hostHeader.replace(/:\d+$/, "");
+    return ALLOWED_HOSTNAMES.has(hostname);
+}
+function FALLBACK_HTML(uiRoot) {
+    return [
+        "<!doctype html><meta charset=utf-8><title>Cool Workflow Workbench</title>",
+        "<body style=\"font-family:system-ui;margin:2rem;color:#222\">",
+        "<h1>Cool Workflow Workbench</h1>",
+        "<p>The static UI assets are not installed at:</p>",
+        `<pre>${escapeHtml(uiRoot)}</pre>`,
+        "<p>The read-only JSON views are still served:</p>",
+        "<ul><li><a href=\"/api/index\">/api/index</a></li><li><code>/api/run/&lt;runId&gt;</code></li><li><a href=\"/api/serve\">/api/serve</a></li></ul>",
+        "</body>"
+    ].join("");
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>]/g, (ch) => (ch === "&" ? "&amp;" : ch === "<" ? "&lt;" : "&gt;"));
+}

package/dist/workbench.js

@@ -0,0 +1,190 @@
+"use strict";
+// Web / Desktop Workbench core (v0.1.30) — the SINGLE source of the human
+// console's view models, and a THIRD FRONT DOOR over ONE mechanism.
+//
+// BSD discipline:
+//  - MECHANISM VS POLICY. The kernel + durable `.cw/` state are the mechanism.
+//    The CLI renders for human speed, MCP for machine context, and the Workbench
+//    for human inspection at a glance. All three are presentation POLICY over the
+//    same data. This module computes, decides, and stores NOTHING the CLI/MCP
+//    cannot already produce — every panel embeds, verbatim, the canonical
+//    `--json` payload of ONE already-declared capability, assembled by calling
+//    the SAME runner core entries the CLI and MCP route through.
+//  - NO HIDDEN DASHBOARD. These are DERIVED, read-only projections. They hold no
+//    authoritative state; refresh re-derives everything from disk. Delete the
+//    host process and nothing is lost — the data is the files.
+//  - EXPLICIT, INSPECTABLE, FAIL CLOSED. When a source capability is unreadable
+//    (e.g. a run with no blackboard yet, or unresolvable state), the panel is
+//    rendered `absent` with the honest error; we never fabricate a view.
+//
+// See docs/web-desktop-workbench.7.md, src/capability-registry.ts, and the
+// v0.1.27 parity contract (docs/cli-mcp-parity.7.md).
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKBENCH_UI_RELATIVE = exports.WORKBENCH_DEFAULT_PORT = void 0;
+exports.buildWorkbenchRunView = buildWorkbenchRunView;
+exports.buildWorkbenchIndex = buildWorkbenchIndex;
+exports.workbenchUiRoot = workbenchUiRoot;
+exports.buildWorkbenchServeDescriptor = buildWorkbenchServeDescriptor;
+const capability_core_1 = require("./capability-core");
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+/** Default loopback port. Local by default, least privilege — never a public
+ *  interface. Overridable with `--port`. */
+exports.WORKBENCH_DEFAULT_PORT = 7717;
+/** Relative location of the optional, dependency-light static UI assets. Kept
+ *  OUT of the kernel: the host reads them lazily at request time, so the framework
+ *  builds and runs with the Workbench (and these files) absent. */
+exports.WORKBENCH_UI_RELATIVE = node_path_1.default.join("ui", "workbench");
+// ---------------------------------------------------------------------------
+// Panel assembly — each panel IS one capability payload, embedded verbatim.
+// ---------------------------------------------------------------------------
+/** Render one panel by invoking its single source capability. On success `data`
+ *  equals `cw <cmd> --json` byte-for-byte; on failure the panel is `absent` with
+ *  the honest reason (fail closed) — exactly what the CLI would report. */
+function panel(capability, cli, mcp, produce) {
+    try {
+        return { capability, cli, mcp, status: "present", data: produce() };
+    }
+    catch (error) {
+        return { capability, cli, mcp, status: "absent", error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function buildPanels(runner, runId) {
+    return {
+        // Run graph — operator + multi-agent, including the v0.1.25 compact and
+        // critical-path views. Backend ids/attestations (v0.1.29) ride on the nodes.
+        graph: {
+            operator: panel("graph", `cw graph ${runId} --json`, "cw_operator_graph", () => runner.operatorGraph(runId)),
+            multiAgent: panel("multi-agent.graph", `cw multi-agent graph ${runId} --json`, "cw_multi_agent_graph", () => runner.multiAgentOperatorGraph(runId)),
+            compact: panel("multi-agent.graph.compact", `cw multi-agent graph ${runId} --view compact --json`, "cw_multi_agent_graph_compact", () => runner.multiAgentGraphView(runId, { view: "compact" })),
+            criticalPath: panel("multi-agent.graph.compact", `cw multi-agent graph ${runId} --view critical-path --json`, "cw_multi_agent_graph_compact", () => runner.multiAgentGraphView(runId, { view: "critical-path" }))
+        },
+        // Blackboard — coordinator topics/messages/contexts/artifacts/snapshots/
+        // decisions/conflicts/adopted+missing evidence.
+        blackboard: {
+            coordinator: panel("coordinator.summary", `cw coordinator summary ${runId}`, "cw_coordinator_summary", () => runner.coordinatorSummary(runId)),
+            digest: panel("blackboard.summarize", `cw blackboard summarize ${runId} --json`, "cw_blackboard_summarize", () => runner.blackboardSummarize(runId)),
+            graph: panel("blackboard.graph", `cw blackboard graph ${runId}`, "cw_blackboard_graph", () => runner.blackboardGraph(runId))
+        },
+        // Worker logs — manifests, outputs, scoped results, failures, and the
+        // recorded execution backend + sandbox attestation.
+        worker: {
+            summary: panel("worker.summary", `cw worker summary ${runId} --json`, "cw_worker_summary", () => runner.summarizeWorkerRecords(runId))
+        },
+        // Candidate compare — scores/selection/rejection, plus the v0.1.26
+        // evidence-adoption reasoning chain (why adopted).
+        candidate: {
+            summary: panel("candidate.summary", `cw candidate summary ${runId} --json`, "cw_candidate_summary", () => runner.summarizeCandidateOperatorRecords(runId)),
+            reasoning: panel("multi-agent.reasoning", `cw multi-agent reasoning ${runId} --json`, "cw_evidence_reasoning", () => runner.multiAgentReasoning(runId))
+        },
+        // Observability + cost (v0.1.31) — durations, failure/verifier/acceptance
+        // rates with sample counts, attested usage + cost, coverage, `unreported`/
+        // `n/a` shown honestly. Equals `cw metrics show <run> --json` byte-for-byte.
+        metrics: {
+            report: panel("metrics.show", `cw metrics show ${runId} --json`, "cw_metrics_show", () => runner.metricsShow(runId))
+        },
+        // Audit timeline — trust-audit events, role policy decisions, provenance,
+        // judge/chair rationale, and policy violations.
+        audit: {
+            summary: panel("audit.summary", `cw audit summary ${runId}`, "cw_audit_summary", () => runner.auditSummary(runId)),
+            multiAgent: panel("audit.multi-agent", `cw audit multi-agent ${runId} --json`, "cw_audit_multi_agent", () => runner.auditMultiAgent(runId)),
+            policy: panel("audit.policy", `cw audit policy ${runId} --json`, "cw_audit_policy", () => runner.auditPolicy(runId)),
+            judge: panel("audit.judge", `cw audit judge ${runId} --json`, "cw_audit_judge", () => runner.auditJudge(runId))
+        },
+        // Collaboration (v0.1.32) — derived per-target review state (pending/approved/
+        // rejected/blocked/unattributed, required vs recorded), the append-only
+        // approval/comment/handoff timeline, and the run owner. Read-only; equals
+        // `cw review status <run> --json` and `cw comment list <run> --json`.
+        collaboration: {
+            review: panel("review.status", `cw review status ${runId} --json`, "cw_review_status", () => runner.reviewStatus(runId)),
+            comments: panel("comment.list", `cw comment list ${runId} --json`, "cw_comment_list", () => runner.collaborationCommentList(runId))
+        }
+    };
+}
+/** Assemble the read-only five-panel view of ONE run. The run is first resolved
+ *  from its durable `.cw/runs/<id>/state.json`; when that source is unreadable
+ *  the view is `resolved: false` and every panel is `absent` — fail closed,
+ *  never fabricated. */
+function buildWorkbenchRunView(runner, runId) {
+    const id = String(runId || "");
+    let resolved = true;
+    let error;
+    try {
+        runner.loadRun(id);
+    }
+    catch (caught) {
+        resolved = false;
+        error = caught instanceof Error ? caught.message : String(caught);
+    }
+    return {
+        schemaVersion: 1,
+        surface: "workbench",
+        runId: id,
+        resolved,
+        ...(error ? { error } : {}),
+        panels: buildPanels(runner, id)
+    };
+}
+// ---------------------------------------------------------------------------
+// Cross-run entry (v0.1.28 Run Registry) — composed from already-declared
+// capabilities; adds NO new source of truth.
+// ---------------------------------------------------------------------------
+/** Build the cross-run index: the registry index plus the run list (or a
+ *  filtered search). Each field equals the corresponding `cw <cmd> --json`
+ *  payload; the Workbench can show nothing the CLI/MCP cannot. */
+function buildWorkbenchIndex(runner, args = {}) {
+    const scope = args.scope === "repo" ? "repo" : "home";
+    const scoped = { ...args, scope };
+    const registry = (0, capability_core_1.runRegistryShow)((0, capability_core_1.runRegistryFor)(scoped, runner), scoped);
+    const filtered = Boolean(args.text || args.q || args.query || args.app || args.appId || args.status || args.repo || args.since || args.until);
+    const runs = filtered ? (0, capability_core_1.runSearch)((0, capability_core_1.runRegistryFor)(scoped, runner), scoped) : (0, capability_core_1.runList)((0, capability_core_1.runRegistryFor)(scoped, runner), scoped);
+    return { schemaVersion: 1, surface: "workbench", command: "index", scope, registry, runs };
+}
+// ---------------------------------------------------------------------------
+// Serve descriptor — describes the OPTIONAL localhost host (no state).
+// ---------------------------------------------------------------------------
+/** Absolute path to the optional static UI assets for this plugin install. */
+function workbenchUiRoot(runner) {
+    return node_path_1.default.join(runner.pluginRoot, exports.WORKBENCH_UI_RELATIVE);
+}
+/** The canonical `cw workbench serve` payload: a description of the localhost
+ *  bind and its read-only routes. Holds zero authoritative state. The CLI emits
+ *  this under `--json`/`--once`; `cw_workbench_serve` returns it directly. */
+function buildWorkbenchServeDescriptor(runner, args = {}) {
+    const scope = args.scope === "repo" ? "repo" : "home";
+    const root = node_path_1.default.resolve(String(args.cwd || process.cwd()));
+    const portRaw = Number(args.port);
+    const port = Number.isFinite(portRaw) && portRaw > 0 ? Math.floor(portRaw) : exports.WORKBENCH_DEFAULT_PORT;
+    const uiRoot = workbenchUiRoot(runner);
+    return {
+        schemaVersion: 1,
+        surface: "workbench",
+        command: "serve",
+        host: "127.0.0.1",
+        port,
+        once: Boolean(args.once),
+        readOnly: true,
+        scope,
+        root,
+        uiAvailable: dirExists(uiRoot),
+        uiRoot,
+        routes: [
+            { method: "GET", path: "/", description: "Workbench UI shell (static, dependency-light)." },
+            { method: "GET", path: "/ui/*", description: "Static UI assets (read from disk; absent if not installed)." },
+            { method: "GET", path: "/api/index", description: "Cross-run index: registry show + run list/search (v0.1.28)." },
+            { method: "GET", path: "/api/serve", description: "This serve descriptor." },
+            { method: "GET", path: "/api/run/:runId", description: "Five-panel WorkbenchRunView for one run (read-only)." }
+        ]
+    };
+}
+function dirExists(target) {
+    try {
+        return node_fs_1.default.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}