cool-workflow 0.1.98 → 0.2.1

package/dist/{multi-agent-trust.js → shell/trust-policy-io.js}

@@ -1,122 +1,56 @@
 "use strict";
+// shell/trust-policy-io.ts — the impure wrapper around core/multi-agent/
+// trust-policy.ts's pure policy evaluation: authorizeMultiAgentAction
+// (records the permission + policy.violation audit events),
+// recordBlackboardWriteAudit, recordMessageProvenanceAudit,
+// recordJudgeRationaleAudit, summarizeMultiAgentTrust,
+// hasAcceptedJudgeRationale.
+//
+// MILESTONE 9. Byte-exact port of the audit-recording half of the old
+// build's src/multi-agent-trust.ts.
+//
+// Evidence: SPEC/multi-agent.md section D ("Trust policies"), "Trust
+// denial reasons"; plugins/cool-workflow/src/multi-agent-trust.ts:129-415
+// (byte-exact source).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.policyForRole = policyForRole;
-exports.policyForGroup = policyForGroup;
-exports.policyForMembership = policyForMembership;
-exports.recordRolePolicyAudit = recordRolePolicyAudit;
+exports.policyForRole = exports.policyForMembership = exports.policyForGroup = void 0;
 exports.authorizeMultiAgentAction = authorizeMultiAgentAction;
 exports.assertMultiAgentActionAllowed = assertMultiAgentActionAllowed;
 exports.recordBlackboardWriteAudit = recordBlackboardWriteAudit;
+exports.hashText = hashText;
 exports.recordMessageProvenanceAudit = recordMessageProvenanceAudit;
 exports.recordJudgeRationaleAudit = recordJudgeRationaleAudit;
 exports.summarizeMultiAgentTrust = summarizeMultiAgentTrust;
 exports.hasAcceptedJudgeRationale = hasAcceptedJudgeRationale;
-exports.sourceForActor = sourceForActor;
-exports.hashText = hashText;
-const execution_backend_1 = require("./execution-backend");
+exports.recordRolePolicyAudit = recordRolePolicyAudit;
+const runtime_1 = require("../core/multi-agent/runtime");
+const trust_policy_1 = require("../core/multi-agent/trust-policy");
 const trust_audit_1 = require("./trust-audit");
-function policyForRole(role) {
-    const topologyRole = String(role.metadata?.topologyRoleId || role.title || "").toLowerCase();
-    const isChair = topologyRole.includes("chair") || topologyRole.includes("reducer") || topologyRole.includes("synthesizer");
-    const isJudge = topologyRole.includes("judge");
-    return {
-        schemaVersion: 1,
-        id: `${role.id}-policy`,
-        policyRef: `multiAgent.roles.${role.id}.policy`,
-        subjectKind: "role",
-        subjectId: role.id,
-        allowedBlackboardTopicIds: unique(role.topicIds || ["*"]),
-        allowedWriteOperations: unique([
-            "message",
-            "context",
-            "artifact",
-            ...(isChair ? ["snapshot", "coordinator-decision"] : [])
-        ]),
-        allowedCandidateOperations: isChair ? ["score", "select"] : ["score"],
-        allowedJudgeOperations: unique([
-            ...(isJudge ? ["verdict", "rationale"] : []),
-            ...(isChair ? ["rationale", "panel-decision"] : [])
-        ]),
-        sandboxProfileHints: unique(role.sandboxProfileHints || []),
-        requiredEvidenceRefs: unique(role.requiredEvidence || []),
-        requiredEvidenceFor: {
-            "judge.rationale": ["judge rationale evidence"],
-            "judge.verdict": ["judge verdict evidence"],
-            "judge.panel-decision": ["judge messages", "score evidence", "coordinator decision"],
-            "candidate.select": ["score evidence", "judge rationale"]
-        },
-        deniedOperations: [],
-        metadata: { title: role.title, topologyRoleId: role.metadata?.topologyRoleId }
-    };
-}
-function policyForGroup(group) {
-    return {
-        schemaVersion: 1,
-        id: `${group.id}-policy`,
-        policyRef: `multiAgent.groups.${group.id}.policy`,
-        subjectKind: "group",
-        subjectId: group.id,
-        allowedBlackboardTopicIds: unique(group.topicIds || ["*"]),
-        allowedWriteOperations: ["message", "context", "artifact", "snapshot", "coordinator-decision"],
-        allowedCandidateOperations: ["register", "score", "select"],
-        allowedJudgeOperations: ["verdict", "rationale", "panel-decision"],
-        sandboxProfileHints: [],
-        requiredEvidenceRefs: [],
-        deniedOperations: [],
-        metadata: { phase: group.phase }
-    };
-}
-function policyForMembership(membership, role) {
-    const source = role?.policy || (role ? policyForRole(role) : undefined);
-    return {
-        ...(source || {
-            schemaVersion: 1,
-            id: `${membership.id}-policy`,
-            policyRef: `multiAgent.memberships.${membership.id}.policy`,
-            subjectKind: "membership",
-            subjectId: membership.id,
-            allowedBlackboardTopicIds: unique(membership.topicIds || ["*"]),
-            allowedWriteOperations: ["message", "context", "artifact"],
-            allowedCandidateOperations: [],
-            allowedJudgeOperations: [],
-            sandboxProfileHints: [],
-            requiredEvidenceRefs: [],
-            deniedOperations: []
-        }),
-        id: `${membership.id}-policy`,
-        policyRef: `multiAgent.memberships.${membership.id}.policy`,
-        subjectKind: "membership",
-        subjectId: membership.id
-    };
-}
-function recordRolePolicyAudit(run, role) {
-    return (0, trust_audit_1.recordTrustAuditEvent)(run, {
-        kind: "multi-agent.role-policy",
-        decision: "recorded",
-        source: "runtime-derived",
-        multiAgentRunId: role.multiAgentRunId,
-        agentRoleId: role.id,
-        blackboardId: role.blackboardId,
-        policyRef: role.policy?.policyRef,
-        metadata: role.policy
-    });
+const hash_1 = require("../core/hash");
+function policyRunId(run, roleId, groupId, membershipId) {
+    const membership = membershipId ? (0, runtime_1.getAgentMembership)(run, membershipId) : undefined;
+    if (membership)
+        return membership.multiAgentRunId;
+    const role = roleId ? (0, runtime_1.getAgentRole)(run, roleId) : undefined;
+    if (role)
+        return role.multiAgentRunId;
+    const group = groupId ? (0, runtime_1.getAgentGroup)(run, groupId) : undefined;
+    return group?.multiAgentRunId;
 }
 function authorizeMultiAgentAction(run, input) {
     const roleId = input.agentRoleId || (input.actor?.kind === "role" ? input.actor.id : undefined);
     const membershipId = input.agentMembershipId || (input.actor?.kind === "membership" ? input.actor.id : undefined);
     const groupId = input.agentGroupId || (input.actor?.kind === "group" ? input.actor.id : undefined);
-    const policy = resolvePolicy(run, { roleId, membershipId, groupId });
-    const reason = evaluatePolicy(policy, input.operation, input.blackboardTopicId, input.evidenceRefs || []);
-    const allowed = !reason;
-    const metadata = {
-        operation: input.operation,
-        reason: reason || "allowed by explicit multi-agent policy",
-        policyRef: policy?.policyRef,
-        ...(input.metadata || {})
-    };
+    const policy = (0, trust_policy_1.resolvePolicy)({ roleId, membershipId, groupId }, {
+        membership: (id) => (0, runtime_1.getAgentMembership)(run, id),
+        role: (id) => (0, runtime_1.getAgentRole)(run, id),
+        group: (id) => (0, runtime_1.getAgentGroup)(run, id),
+    });
+    const core = (0, trust_policy_1.evaluateMultiAgentAction)(policy, input.operation, input.blackboardTopicId, input.evidenceRefs || []);
+    const metadata = { operation: input.operation, reason: core.reason, policyRef: policy?.policyRef, ...(input.metadata || {}) };
     const event = (0, trust_audit_1.recordTrustAuditEvent)(run, {
         kind: "multi-agent.permission",
-        decision: allowed ? "allowed" : "denied",
+        decision: core.allowed ? "allowed" : "denied",
         source: "cw-validated",
         actor: input.actor?.id,
         multiAgentRunId: input.multiAgentRunId || policyRunId(run, roleId, groupId, membershipId),
@@ -140,9 +74,9 @@ function authorizeMultiAgentAction(run, input) {
         evidence: input.evidence,
         evidenceRefs: input.evidenceRefs,
         policyRef: policy?.policyRef,
-        metadata
+        metadata,
     });
-    if (!allowed) {
+    if (!core.allowed) {
         (0, trust_audit_1.recordTrustAuditEvent)(run, {
             kind: "policy.violation",
             decision: "denied",
@@ -159,18 +93,10 @@ function authorizeMultiAgentAction(run, input) {
             evidenceRefs: input.evidenceRefs,
             parentEventIds: [event.id],
             policyRef: policy?.policyRef,
-            metadata
+            metadata,
         });
     }
-    return {
-        allowed,
-        decision: allowed ? "allowed" : "denied",
-        reason: reason || "allowed by explicit multi-agent policy",
-        policyRef: policy?.policyRef,
-        policy,
-        missingEvidenceRefs: missingEvidence(policy, input.operation, input.evidenceRefs || []),
-        event
-    };
+    return { allowed: core.allowed, decision: core.decision, reason: core.reason, policyRef: core.policyRef, policy: core.policy, missingEvidenceRefs: core.missingEvidenceRefs, event };
 }
 function assertMultiAgentActionAllowed(run, input) {
     const decision = authorizeMultiAgentAction(run, input);
@@ -178,6 +104,17 @@ function assertMultiAgentActionAllowed(run, input) {
         throw new Error(decision.reason);
     return decision;
 }
+function sourceForActor(actor) {
+    if (!actor)
+        return "operator-recorded";
+    if (actor.kind === "worker")
+        return "host-attested";
+    if (actor.kind === "operator")
+        return "operator-recorded";
+    if (actor.kind === "runtime" || actor.kind === "coordinator" || actor.kind === "verifier")
+        return "runtime-derived";
+    return "cw-validated";
+}
 function recordBlackboardWriteAudit(run, input) {
     return (0, trust_audit_1.recordTrustAuditEvent)(run, {
         kind: "blackboard.write",
@@ -200,9 +137,12 @@ function recordBlackboardWriteAudit(run, input) {
         evidenceRefs: input.evidenceRefs,
         parentEventIds: input.parentEventIds,
         policyRef: input.policyRef,
-        metadata: { operation: input.operation, status: input.status, ...(input.metadata || {}) }
+        metadata: { operation: input.operation, status: input.status, ...(input.metadata || {}) },
     });
 }
+function hashText(value) {
+    return (0, hash_1.sha256)(value);
+}
 function recordMessageProvenanceAudit(run, input) {
     return (0, trust_audit_1.recordTrustAuditEvent)(run, {
         kind: "blackboard.message-provenance",
@@ -226,8 +166,8 @@ function recordMessageProvenanceAudit(run, input) {
             summary: input.body.trim().slice(0, 120),
             parentMessageIds: input.parentMessageIds || [],
             topicScope: input.topicId,
-            locator: `${input.blackboardId}/messages/${input.messageId}`
-        }
+            locator: `${input.blackboardId}/messages/${input.messageId}`,
+        },
     });
 }
 function recordJudgeRationaleAudit(run, input) {
@@ -250,12 +190,13 @@ function recordJudgeRationaleAudit(run, input) {
         evidenceRefs: input.evidenceRefs,
         parentEventIds: input.parentEventIds,
         policyRef: input.policyRef,
-        metadata: { rationale: input.rationale?.slice(0, 240) }
+        metadata: { rationale: input.rationale?.slice(0, 240) },
     });
 }
 function summarizeMultiAgentTrust(run) {
     const events = (0, trust_audit_1.listTrustAuditEvents)(run);
-    const rolePolicies = (run.multiAgent?.roles || []).map((role) => role.policy || policyForRole(role));
+    const roles = (run.multiAgent?.roles || []);
+    const rolePolicies = roles.map((role) => role.policy || (0, trust_policy_1.policyForRole)(role));
     const byKind = (kind) => events.filter((event) => event.kind === kind);
     const policyViolations = byKind("policy.violation");
     return {
@@ -268,9 +209,7 @@ function summarizeMultiAgentTrust(run) {
         judgeRationales: byKind("judge.rationale"),
         panelDecisions: byKind("judge.panel-decision"),
         policyViolations,
-        nextAction: policyViolations.length
-            ? `node scripts/cw.js audit policy ${run.id}`
-            : `node scripts/cw.js audit multi-agent ${run.id} --json`
+        nextAction: policyViolations.length ? `node scripts/cw.js audit policy ${run.id}` : `node scripts/cw.js audit multi-agent ${run.id} --json`,
     };
 }
 function hasAcceptedJudgeRationale(run, input = {}) {
@@ -280,87 +219,10 @@ function hasAcceptedJudgeRationale(run, input = {}) {
         (!input.candidateId || event.candidateId === input.candidateId) &&
         (!input.scoreId || !event.scoreId || event.scoreId === input.scoreId));
 }
-function sourceForActor(actor) {
-    if (!actor)
-        return "operator-recorded";
-    if (actor.kind === "worker")
-        return "host-attested";
-    if (actor.kind === "operator")
-        return "operator-recorded";
-    if (actor.kind === "runtime" || actor.kind === "coordinator" || actor.kind === "verifier")
-        return "runtime-derived";
-    return "cw-validated";
-}
-// Delegates to the shared execution-backend sha256 (F10 dedup). Byte-identical:
-// both emit `sha256:<hex>` and Node's Hash.update(string) defaults to utf8, the
-// same encoding the shared helper passes explicitly.
-function hashText(value) {
-    return (0, execution_backend_1.sha256)(value);
-}
-function resolvePolicy(run, input) {
-    const membership = input.membershipId ? run.multiAgent?.memberships.find((entry) => entry.id === input.membershipId) : undefined;
-    if (membership?.policy)
-        return membership.policy;
-    const roleId = input.roleId || membership?.roleId;
-    const role = roleId ? run.multiAgent?.roles.find((entry) => entry.id === roleId) : undefined;
-    if (role?.policy)
-        return role.policy;
-    if (role)
-        return policyForRole(role);
-    const group = input.groupId ? run.multiAgent?.groups.find((entry) => entry.id === input.groupId) : undefined;
-    if (group?.policy)
-        return group.policy;
-    if (group)
-        return policyForGroup(group);
-    return undefined;
-}
-function evaluatePolicy(policy, operation, topicId, evidenceRefs) {
-    if (!policy)
-        return "missing role authority or policy";
-    const denied = policy.deniedOperations.find((entry) => entry.operation === operation);
-    if (denied)
-        return denied.reason;
-    if (topicId && policy.allowedBlackboardTopicIds.length && !policy.allowedBlackboardTopicIds.includes("*") && !policy.allowedBlackboardTopicIds.includes(topicId)) {
-        return `topic ${topicId} is outside policy ${policy.policyRef}`;
-    }
-    if (operation.startsWith("candidate.")) {
-        const op = operation.slice("candidate.".length);
-        if (!policy.allowedCandidateOperations.includes(op))
-            return `candidate operation ${op} is outside policy ${policy.policyRef}`;
-    }
-    else if (operation.startsWith("judge.")) {
-        const op = operation.slice("judge.".length);
-        if (!policy.allowedJudgeOperations.includes(op))
-            return `judge operation ${op} is outside policy ${policy.policyRef}`;
-    }
-    else if (!policy.allowedWriteOperations.includes(operation)) {
-        return `blackboard write operation ${operation} is outside policy ${policy.policyRef}`;
-    }
-    const missing = missingEvidence(policy, operation, evidenceRefs);
-    if (missing.length)
-        return `operation ${operation} requires evidence refs: ${missing.join(", ")}`;
-    return undefined;
-}
-function missingEvidence(policy, operation, evidenceRefs) {
-    if (!policy)
-        return [];
-    const required = unique([...(policy.requiredEvidenceFor?.[operation] || [])]);
-    if (!required.length)
-        return [];
-    if (evidenceRefs.length)
-        return [];
-    return required;
-}
-function policyRunId(run, roleId, groupId, membershipId) {
-    const membership = membershipId ? run.multiAgent?.memberships.find((entry) => entry.id === membershipId) : undefined;
-    if (membership)
-        return membership.multiAgentRunId;
-    const role = roleId ? run.multiAgent?.roles.find((entry) => entry.id === roleId) : undefined;
-    if (role)
-        return role.multiAgentRunId;
-    const group = groupId ? run.multiAgent?.groups.find((entry) => entry.id === groupId) : undefined;
-    return group?.multiAgentRunId;
-}
-function unique(values) {
-    return Array.from(new Set(values.filter(Boolean)));
+function recordRolePolicyAudit(run, role) {
+    return (0, trust_audit_1.recordTrustAuditEvent)(run, { kind: "multi-agent.role-policy", decision: "recorded", source: "runtime-derived", multiAgentRunId: role.multiAgentRunId, agentRoleId: role.id, blackboardId: role.blackboardId, policyRef: role.policy?.policyRef, metadata: role.policy });
 }
+var trust_policy_2 = require("../core/multi-agent/trust-policy");
+Object.defineProperty(exports, "policyForGroup", { enumerable: true, get: function () { return trust_policy_2.policyForGroup; } });
+Object.defineProperty(exports, "policyForMembership", { enumerable: true, get: function () { return trust_policy_2.policyForMembership; } });
+Object.defineProperty(exports, "policyForRole", { enumerable: true, get: function () { return trust_policy_2.policyForRole; } });

package/dist/shell/verifier.js

@@ -0,0 +1,48 @@
+"use strict";
+// shell/verifier.ts — taskRequiresEvidence, the small task-level gate the
+// worker-accept path and the commit gate both consult.
+//
+// MILESTONE 6+7 (combined). Byte-exact port of the old build's
+// src/verifier.ts's `taskRequiresEvidence`. Pure logic; kept under
+// shell/ only because its caller (worker-isolation.ts) is shell-side —
+// the function itself takes no fs/clock/random input.
+//
+// Evidence: SPEC/pipeline-run.md "Commit gate" (verifierNodeRequiresEvidence
+// reuses this exact predicate).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskRequiresEvidence = taskRequiresEvidence;
+exports.validateResultEnvelope = validateResultEnvelope;
+const evidence_grounding_1 = require("../core/trust/evidence-grounding");
+const schema_validate_1 = require("../core/state/schema-validate");
+function taskRequiresEvidence(task) {
+    return Boolean(task.requiresEvidence || /^verify[:/]/i.test(task.id) || /^verdict[:/]/i.test(task.id) || /^synthesis[:/]/i.test(task.id));
+}
+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)`);
+    }
+}
+/** Validate an accepted result envelope against the task's declared contract:
+ *  required grounded evidence, per-finding shape, and (opt-in) the task's
+ *  declared output schema. Throws on violation (fail-closed — the drive parks
+ *  the hop). Byte-behavior port of the old build's src/verifier.ts. */
+function validateResultEnvelope(task, result) {
+    if (taskRequiresEvidence(task) && !(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);
+    }
+    const schema = task.schema;
+    if (schema) {
+        const violations = (0, schema_validate_1.validateAgainstSchema)(result, 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)` : ""}`);
+        }
+    }
+}

package/dist/shell/workbench-host.js

@@ -0,0 +1,258 @@
+"use strict";
+// shell/workbench-host.ts — the localhost-only, read-only Workbench HTTP
+// server: `cw workbench serve`.
+//
+// MILESTONE 11 (reporting/observability). Byte-exact port of the old
+// build's src/workbench-host.ts's HTTP behavior: loopback bind only,
+// GET-only, non-localhost Host header refused, optional bearer-token
+// auth (timing-safe compare), pretty (2-space) JSON responses with
+// `Cache-Control: no-store` + `X-Content-Type-Options: nosniff`, a fixed
+// fallback index page when the UI is not installed, and `--once`/`--json`
+// printing only the descriptor and starting nothing.
+//
+// CRITICAL: the MCP path (mcp/dispatch.ts) must NEVER start a persistent
+// listener — it always forces `once: true` so `cw_workbench_serve` only
+// ever returns the descriptor. Only the CLI's default (no `--once`, no
+// `--json`) actually binds and blocks.
+//
+// Evidence: SPEC/reporting-ux.md "Workbench" (HTTP behavior, allowed
+// hostnames, serve descriptor stdout line), invariant 11.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkbenchHost = void 0;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const http = __importStar(require("node:http"));
+const path = __importStar(require("node:path"));
+const node_url_1 = require("node:url");
+const workbench_1 = require("./workbench");
+const ALLOWED_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+function timingSafeEqual(a, b) {
+    const bufA = Buffer.from(a, "utf8");
+    const bufB = Buffer.from(b, "utf8");
+    if (bufA.length !== bufB.length) {
+        // Compare against a same-length dummy so the check still takes
+        // constant time relative to the (wrong) input length, matching the
+        // old build's mismatched-length handling.
+        crypto.timingSafeEqual(bufA, bufA);
+        return false;
+    }
+    return crypto.timingSafeEqual(bufA, bufB);
+}
+function sendJson(res, status, body) {
+    const text = `${JSON.stringify(body, null, 2)}\n`;
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+    res.end(text);
+}
+function contentTypeFor(file) {
+    const ext = path.extname(file).toLowerCase();
+    const map = { ".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" };
+    return map[ext] || "application/octet-stream";
+}
+function fallbackIndexHtml(descriptor) {
+    const routeLines = descriptor.routes.map((r) => `<li><code>${r.path}</code> — ${r.description}</li>`).join("\n    ");
+    return `<!doctype html>
+<html>
+  <head><meta charset="utf-8"><title>Cool Workflow Workbench</title></head>
+  <body>
+    <h1>Cool Workflow Workbench</h1>
+    <p>The Workbench UI is not installed. Read-only JSON routes:</p>
+    <ul>
+    ${routeLines}
+    </ul>
+  </body>
+</html>
+`;
+}
+class WorkbenchHost {
+    args;
+    token;
+    server;
+    constructor(args = {}) {
+        this.args = args;
+        this.token = process.env.CW_WORKBENCH_TOKEN && process.env.CW_WORKBENCH_TOKEN.trim() ? process.env.CW_WORKBENCH_TOKEN.trim() : undefined;
+    }
+    /** The serve descriptor; `boundPort` is filled in only after `listen()`
+     *  actually binds (an ephemeral `--port 0` resolves to its real port). */
+    descriptor(once, boundPort) {
+        return (0, workbench_1.buildWorkbenchServeDescriptor)({ ...this.args, once }, boundPort);
+    }
+    checkAuth(req, url) {
+        if (!this.token)
+            return true;
+        const header = req.headers.authorization;
+        const bearer = header && header.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+        const queryToken = url.searchParams.get("token") || undefined;
+        const provided = bearer || queryToken;
+        if (!provided)
+            return false;
+        return timingSafeEqual(provided, this.token);
+    }
+    handleRequest(req, res) {
+        try {
+            const hostHeader = req.headers.host;
+            if (hostHeader) {
+                const hostname = hostHeader.split(":")[0];
+                if (!ALLOWED_HOSTNAMES.has(hostname)) {
+                    sendJson(res, 403, { error: "forbidden: non-localhost Host header" });
+                    return;
+                }
+            }
+            if (req.method !== "GET") {
+                res.setHeader("Allow", "GET");
+                sendJson(res, 405, { error: "read-only: only GET is permitted" });
+                return;
+            }
+            let url;
+            try {
+                url = new node_url_1.URL(req.url || "/", "http://127.0.0.1");
+            }
+            catch {
+                sendJson(res, 400, { error: "bad request: invalid URL" });
+                return;
+            }
+            if (!this.checkAuth(req, url)) {
+                sendJson(res, 401, { error: "unauthorized: token mismatch" });
+                return;
+            }
+            // Decode the route path ONCE (old build's decodeRoutePath). Node's
+            // `new URL()` does NOT throw on a malformed percent-escape like
+            // `/%E0%A4%A`; only decodeURIComponent does — so this is where a
+            // malformed URL is caught as a 400 client error (not a 404, not a
+            // 500 crash). The decoded route is also what the traversal guard
+            // inspects, so an encoded `..%2f..%2f` unescapes to `../../` BEFORE
+            // path.resolve, letting it escape uiRoot and fail 403.
+            let route;
+            try {
+                route = decodeURIComponent(url.pathname);
+            }
+            catch {
+                sendJson(res, 400, { error: "bad request: malformed URL path" });
+                return;
+            }
+            if (route === "/api/serve") {
+                sendJson(res, 200, this.descriptor(false));
+                return;
+            }
+            if (route === "/api/index") {
+                const scope = this.args.scope === "home" ? "home" : "repo";
+                sendJson(res, 200, (0, workbench_1.buildWorkbenchIndex)({ ...this.args, scope, ...Object.fromEntries(url.searchParams.entries()) }));
+                return;
+            }
+            const runMatch = route.match(/^\/api\/run\/([^/]+)$/);
+            if (runMatch) {
+                const runId = runMatch[1];
+                sendJson(res, 200, (0, workbench_1.buildWorkbenchRunView)(runId, this.args));
+                return;
+            }
+            if (route === "/" || route.startsWith("/ui/")) {
+                this.serveUiAsset(route, res);
+                return;
+            }
+            sendJson(res, 404, { error: `no such read-only view: ${route}` });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    serveUiAsset(pathname, res) {
+        const uiRoot = (0, workbench_1.workbenchUiRoot)();
+        const relative = pathname === "/" ? "index.html" : pathname.replace(/^\/ui\//, "");
+        const resolved = path.resolve(uiRoot, relative);
+        if (!resolved.startsWith(path.resolve(uiRoot) + path.sep) && resolved !== path.resolve(uiRoot)) {
+            sendJson(res, 403, { error: "forbidden: path traversal" });
+            return;
+        }
+        if (pathname === "/" && !fs.existsSync(resolved)) {
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+            res.end(fallbackIndexHtml(this.descriptor(false)));
+            return;
+        }
+        if (!fs.existsSync(resolved) || fs.statSync(resolved).isDirectory()) {
+            sendJson(res, 404, { error: `UI asset not installed: ${relative}` });
+            return;
+        }
+        res.writeHead(200, { "Content-Type": contentTypeFor(resolved), "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+        res.end(fs.readFileSync(resolved));
+    }
+    /** Binds the loopback server and resolves once listening. Returns the
+     *  actually-bound port (useful for `--port 0`). */
+    listen() {
+        return new Promise((resolve, reject) => {
+            const server = http.createServer((req, res) => this.handleRequest(req, res));
+            const requestedPort = this.args.port !== undefined ? Number(this.args.port) : undefined;
+            server.on("error", reject);
+            server.listen(requestedPort ?? 7717, "127.0.0.1", () => {
+                this.server = server;
+                const address = server.address();
+                resolve(typeof address === "object" && address ? address.port : requestedPort || 7717);
+            });
+        });
+    }
+    close() {
+        return new Promise((resolve) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.server.close(() => resolve());
+        });
+    }
+    /** `cw workbench serve` entry point: `--once`/`--json` prints ONLY the
+     *  descriptor (compact JSON) and starts nothing; the default binds and
+     *  blocks, printing one compact line (`{...descriptor, boundPort}`)
+     *  once listening. `--require-token` is a strict opt-in: default behavior
+     *  (unauthenticated local reads when no token is configured) is
+     *  unchanged unless the caller explicitly asks to fail closed. */
+    async run() {
+        const requireToken = Boolean(this.args.requireToken || this.args["require-token"]);
+        if (requireToken && !this.token) {
+            process.stderr.write("workbench serve --require-token: CW_WORKBENCH_TOKEN is not set; refusing to start.\n");
+            process.exitCode = 1;
+            return;
+        }
+        const once = Boolean(this.args.once || this.args.json);
+        if (once) {
+            process.stdout.write(`${JSON.stringify(this.descriptor(true))}\n`);
+            return;
+        }
+        const boundPort = await this.listen();
+        const descriptor = this.descriptor(false, boundPort);
+        process.stdout.write(`${JSON.stringify({ ...descriptor, boundPort })}\n`);
+        // Block forever (until the process is killed) — a real serve.
+        await new Promise(() => { });
+    }
+}
+exports.WorkbenchHost = WorkbenchHost;