smol-symphony 0.2.0 → 0.3.1

package/dist/core/workflow/parse.js

@@ -0,0 +1,687 @@
+// FCIS rewrite — PURE workflow (WORKFLOW.yaml) parser + typed ServiceConfig builder.
+//
+// Ports the original `src/workflow.ts` parse path (parseWorkflow, expandVar,
+// buildServiceConfig) into the functional
+// core. 100% synchronous, zero IO, imports ONLY from src/types. The legacy
+// fenced front-matter + inline Markdown body form was removed: a workflow file
+// is now pure YAML config (prompts live in per-state `prompt_file`s).
+//
+// How the original's impure dependencies are made pure here:
+//   * YAML decode (the `yaml` package in the original's parseFrontMatter) is
+//     INJECTED as `deps.parseYaml`. The shell wires in `yaml.parse`; the core
+//     never imports the library.
+//   * `node:path` / `node:os` (path.resolve/dirname/join/isAbsolute, os.homedir)
+//     are replaced with pure POSIX helpers below; the home dir comes from the
+//     injected WorkflowEnv (HOME), so the parser reads no real environment.
+//   * The `actions:` sub-block parser lives in the sibling core module
+//     src/core/actions/parse.ts. It is INJECTABLE as `deps.parseActions` (so the
+//     shell can curry it) but defaults to that module's `parseActionsBlock`.
+import { WorkflowError } from '../../types/errors.js';
+import { parseActionsBlock } from '../actions/parse.js';
+import { MISE_EGRESS_HOSTS } from '../runner/mise.js';
+import { asString, asIntOr, asStringListOr } from '../coerce.js';
+import { sanitizeWorkspaceKey } from '../workspace-key.js';
+// ─── pure POSIX path helpers (replace node:path; no IO) ──────────────────────
+//
+// The original used node:path. These are deliberately POSIX-only — the
+// orchestrator runs on Linux/macOS hosts — and operate purely on strings. They
+// faithfully reproduce path.{isAbsolute,join,resolve,dirname} for the inputs the
+// parser sees (absolute workflow paths + relative config values). POSIX-only is
+// intentional and matches the original's runtime targets.
+function isAbsolute(p) {
+    return p.startsWith('/');
+}
+function normalizeSegments(segments, allowLeadingDotDot) {
+    const out = [];
+    for (const seg of segments) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            if (out.length > 0 && out[out.length - 1] !== '..')
+                out.pop();
+            else if (allowLeadingDotDot)
+                out.push('..');
+            continue;
+        }
+        out.push(seg);
+    }
+    return out;
+}
+function joinPath(...parts) {
+    const joined = parts.filter((p) => p.length > 0).join('/');
+    if (joined === '')
+        return '.';
+    const absolute = joined.startsWith('/');
+    const segs = normalizeSegments(joined.split('/'), !absolute);
+    const body = segs.join('/');
+    if (absolute)
+        return '/' + body;
+    return body === '' ? '.' : body;
+}
+/**
+ * Resolve `to` against `from` (defaults to a cwd derived from the env). Faithful
+ * to path.resolve for the parser's use: an absolute input is normalized; a
+ * relative input is joined onto its base. Unlike node:path.resolve we never read
+ * the real cwd — a relative base resolves against the injected `cwd`.
+ */
+function resolvePath(cwd, ...parts) {
+    let resolved = '';
+    let isAbs = false;
+    // Walk right-to-left like path.resolve, prepending until we hit an absolute.
+    for (let i = parts.length - 1; i >= 0 && !isAbs; i--) {
+        const part = parts[i];
+        if (part.length === 0)
+            continue;
+        resolved = resolved.length === 0 ? part : part + '/' + resolved;
+        isAbs = part.startsWith('/');
+    }
+    if (!isAbs) {
+        resolved = resolved.length === 0 ? cwd : cwd + '/' + resolved;
+    }
+    const absolute = resolved.startsWith('/');
+    const segs = normalizeSegments(resolved.split('/'), false);
+    const body = segs.join('/');
+    if (absolute)
+        return '/' + body;
+    return body === '' ? '.' : body;
+}
+function dirname(p) {
+    const norm = p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p;
+    const idx = norm.lastIndexOf('/');
+    if (idx < 0)
+        return '.';
+    if (idx === 0)
+        return '/';
+    return norm.slice(0, idx);
+}
+/** Last path segment (replaces node:path.basename for the project-namespace fallback). */
+function basename(p) {
+    const norm = p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p;
+    const idx = norm.lastIndexOf('/');
+    return idx < 0 ? norm : norm.slice(idx + 1);
+}
+/** Home directory from the injected env (replaces os.homedir(); no IO). */
+function homeDir(env) {
+    const h = env['HOME'] ?? env['USERPROFILE'];
+    return h && h.length > 0 ? h : '/root';
+}
+/** The base cwd a relative workflow path resolves against (env PWD, else "/"). */
+function cwdOf(env) {
+    const pwd = env['PWD'];
+    return pwd && isAbsolute(pwd) ? pwd : '/';
+}
+// ─── home-based path defaults (issue 210) ────────────────────────────────────
+//
+// When a `*.root` is UNSET, durable operator state defaults under a per-project
+// home base (~/.symphony/<kind>/<project>) instead of inside the repo working
+// tree or tmpdir — so it survives a `rm -rf`/re-clone of the repo (or a reboot,
+// for the old tmpdir workspaces). An EXPLICIT root is unaffected: it still
+// resolves exactly as before (absolute as-is, `~`-expanded, relative →
+// workflowDir). Only the unset-default branch routes through here.
+/**
+ * The `<project>` namespace for the home-based path defaults. Derived from the
+ * `workspace.github_repo` slug (owner/repo → repo), falling back to the
+ * workflow-dir basename. Sanitized with the canonical workspace-key sanitizer so
+ * two different projects on one machine never collide under the shared
+ * `~/.symphony/<kind>/` base (the supported topology is one instance per project,
+ * many across DIFFERENT projects). An empty result falls back to "symphony".
+ */
+function deriveProjectNamespace(githubRepo, workflowDir) {
+    const raw = githubRepo ? (githubRepo.split('/').pop() ?? '') : basename(workflowDir);
+    const sanitized = sanitizeWorkspaceKey(raw.trim());
+    return sanitized.length > 0 ? sanitized : 'symphony';
+}
+/** Home-based default root for an unset `*.root`: ~/.symphony/<kind>/<project>. */
+function homeDefaultRoot(env, kind, project) {
+    return joinPath(homeDir(env), '.symphony', kind, project);
+}
+// ─── workflow YAML decode (§4.2) ──────────────────────────────────────────────
+/**
+ * Decode a workflow file (pure YAML) to a config map. A workflow file is pure
+ * YAML config — the whole file decodes to the config map and prompts come from
+ * per-state `prompt_file`s (+ the shared `prompt.preamble_file`/`footer_file`).
+ * Empty/whitespace decodes to `{}`; a non-map (list, scalar) throws
+ * `workflow_front_matter_not_a_map`; any other decode failure throws
+ * `workflow_parse_error`.
+ */
+export function decodeYamlMap(text, parseYaml) {
+    let parsed;
+    try {
+        parsed = text.trim().length === 0 ? {} : parseYaml(text);
+    }
+    catch (err) {
+        throw new WorkflowError('workflow_parse_error', `invalid workflow YAML: ${err.message}`);
+    }
+    if (parsed === null || parsed === undefined)
+        parsed = {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new WorkflowError('workflow_front_matter_not_a_map', 'workflow YAML must decode to a map');
+    }
+    return parsed;
+}
+/**
+ * Pure entry point: decode the workflow YAML, build the typed view, and return
+ * both shapes. `env` supplies the `$VAR`/`~` variable map (the shell loader
+ * passes process.env; tests pass an explicit shape). `deps.parseYaml` decodes
+ * the config; `deps.parseActions` parses per-state `actions:` blocks.
+ */
+export function parseWorkflow(text, workflowPath, deps, env = {}) {
+    // A workflow file is pure YAML config: the whole file decodes to the config
+    // map and each active state renders its own `prompt_file` (wrapped in the
+    // shared `prompt.preamble_file`/`footer_file`). The legacy fenced
+    // front-matter + inline Markdown body form was removed (no backward compat).
+    const raw = decodeYamlMap(text, deps.parseYaml);
+    const definition = { config: raw };
+    const built = buildServiceConfig(raw, workflowPath, deps, env);
+    return { definition, config: built.config };
+}
+// ─── $VAR / ~ expansion (pure) ────────────────────────────────────────────────
+/**
+ * `$VAR` / `~` expansion for path/command fields. `~`/`~/x` expand against the
+ * injected env's HOME; a bare `$NAME` resolves from `env` (empty string when
+ * unset, matching the original). Other strings pass through unchanged.
+ */
+export function expandVar(value, env = {}) {
+    if (typeof value !== 'string')
+        return value;
+    let s = value;
+    if (s.startsWith('~/') || s === '~') {
+        s = s === '~' ? homeDir(env) : joinPath(homeDir(env), s.slice(2));
+    }
+    const m = s.match(/^\$([A-Z_][A-Z0-9_]*)$/);
+    if (m) {
+        const envVal = env[m[1]];
+        return envVal ?? '';
+    }
+    return s;
+}
+// ─── scalar coercion helpers ─────────────────────────────────────────────────
+// asString / asInt / asStringList are the canonical coercers from core/coerce.ts
+// (asString imported directly; the fallback-taking config forms are local
+// aliases over asIntOr / asStringListOr so the 20+ call sites are unchanged).
+const asInt = asIntOr;
+const asStringList = asStringListOr;
+/** A non-empty (post-trim) string, or the fallback (so a blank config value defaults). */
+function nonEmptyOr(v, fallback) {
+    if (typeof v === 'string' && v.trim().length > 0)
+        return v.trim();
+    return fallback;
+}
+function getObject(parent, key) {
+    const v = parent[key];
+    if (v && typeof v === 'object' && !Array.isArray(v))
+        return v;
+    return {};
+}
+// workspace.github_repo validation: a literal `owner/repo` slug, or null. See the
+// original for the rationale (reject whole-URL/SSH/bare names at parse time).
+function parseGithubRepo(input) {
+    if (input === undefined || input === null)
+        return null;
+    if (typeof input !== 'string') {
+        throw new WorkflowError('workflow_parse_error', `workspace.github_repo must be a string "owner/repo" slug or "none" (got ${typeof input})`);
+    }
+    const trimmed = input.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'none')
+        return null;
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/.test(trimmed)) {
+        throw new WorkflowError('workflow_parse_error', `workspace.github_repo must be a GitHub "owner/repo" slug or "none" (got: ${input})`);
+    }
+    return trimmed;
+}
+// gondolin.oci_pull_policy: the OCI pull behavior before conversion (issue 206).
+// Defaults to `if-not-present`; rejects any other string at parse time so a typo
+// surfaces here, not at the first reconcile build.
+function parseOciPullPolicy(input) {
+    if (input === undefined || input === null)
+        return 'if-not-present';
+    const s = asString(input);
+    if (s === 'if-not-present' || s === 'always' || s === 'never')
+        return s;
+    throw new WorkflowError('workflow_parse_error', `gondolin.oci_pull_policy must be one of if-not-present|always|never (got: ${String(input)})`);
+}
+// gondolin.oci_runtime: the container runtime for the conversion pull/export
+// (issue 206). Null/unset = auto-detect; rejects any value other than docker/podman.
+function parseOciRuntime(input) {
+    if (input === undefined || input === null)
+        return null;
+    const s = asString(input);
+    if (s === null || s.trim().length === 0)
+        return null;
+    const trimmed = s.trim();
+    if (trimmed === 'docker' || trimmed === 'podman')
+        return trimmed;
+    throw new WorkflowError('workflow_parse_error', `gondolin.oci_runtime must be docker or podman (got: ${String(input)})`);
+}
+/**
+ * Build a fully typed ServiceConfig from a parsed workflow YAML config map. Pure. The
+ * `env` supplies the `$VAR`/`~` variable map; `deps.parseActions` parses per-state
+ * `actions:` blocks.
+ */
+export function buildServiceConfig(raw, workflowPath, deps, env = {}) {
+    const cwd = cwdOf(env);
+    const parseActions = deps.parseActions ?? parseActionsBlock;
+    const workflowAbs = resolvePath(cwd, workflowPath);
+    const workflowDir = dirname(workflowAbs);
+    // Home-default project namespace (issue 210): parse workspace.github_repo once
+    // here so the unset-root defaults of tracker / workspaces / logs can land under
+    // ~/.symphony/<kind>/<project>. (workspaceRaw + githubRepo are reused by the
+    // workspace block below.)
+    const workspaceRaw = getObject(raw, 'workspace');
+    const githubRepo = parseGithubRepo(workspaceRaw['github_repo']);
+    const projectNamespace = deriveProjectNamespace(githubRepo, workflowDir);
+    // tracker (§4.3.1)
+    const trackerRaw = getObject(raw, 'tracker');
+    const trackerKind = (asString(trackerRaw['kind']) ?? '').trim();
+    const trackerRootRaw = asString(trackerRaw['root']);
+    let trackerRoot = null;
+    if (trackerRootRaw) {
+        const expanded = expandVar(trackerRootRaw, env);
+        if (expanded === '') {
+            throw new WorkflowError('workflow_parse_error', `tracker.root references an unset variable: ${trackerRootRaw}`);
+        }
+        trackerRoot = isAbsolute(expanded) ? expanded : resolvePath(workflowDir, expanded);
+    }
+    else if (trackerKind === 'local') {
+        trackerRoot = homeDefaultRoot(env, 'trackers', projectNamespace);
+    }
+    const states = parseStatesBlock(raw['states'], parseActions);
+    const tracker = { kind: trackerKind, states, root: trackerRoot };
+    // prompt files (per-state prompt split). Resolve a workflow-relative or
+    // `$VAR`/`~` path to an absolute path the shell loader reads off disk. Shared
+    // by the per-state `prompt_file` and the `prompt.{preamble,footer}_file`.
+    const resolvePromptPath = (value, label) => {
+        const expanded = expandVar(value, env);
+        if (expanded === '') {
+            throw new WorkflowError('workflow_parse_error', `${label} references an unset variable: ${value}`);
+        }
+        return isAbsolute(expanded) ? expanded : resolvePath(workflowDir, expanded);
+    };
+    for (const [name, sc] of Object.entries(states)) {
+        if (sc.prompt_file)
+            sc.prompt_file = resolvePromptPath(sc.prompt_file, `state "${name}": prompt_file`);
+    }
+    const promptRaw = getObject(raw, 'prompt');
+    const preambleFileRaw = asString(promptRaw['preamble_file']);
+    const footerFileRaw = asString(promptRaw['footer_file']);
+    const prompt = {
+        preamble_file: preambleFileRaw && preambleFileRaw.trim().length > 0
+            ? resolvePromptPath(preambleFileRaw.trim(), 'prompt.preamble_file')
+            : null,
+        footer_file: footerFileRaw && footerFileRaw.trim().length > 0
+            ? resolvePromptPath(footerFileRaw.trim(), 'prompt.footer_file')
+            : null,
+    };
+    // polling (§4.3.2)
+    const pollingRaw = getObject(raw, 'polling');
+    const polling = { interval_ms: asInt(pollingRaw['interval_ms'], 30_000) };
+    // workspace (§4.3.3). workspaceRaw + githubRepo were parsed above (the home
+    // project namespace needs github_repo before the tracker default).
+    const wsRootInput = asString(workspaceRaw['root']);
+    let workspaceRoot;
+    if (wsRootInput) {
+        const expanded = expandVar(wsRootInput, env);
+        if (expanded === '') {
+            throw new WorkflowError('workflow_parse_error', `workspace.root references an unset variable: ${wsRootInput}`);
+        }
+        workspaceRoot = isAbsolute(expanded) ? expanded : resolvePath(workflowDir, expanded);
+    }
+    else {
+        workspaceRoot = homeDefaultRoot(env, 'workspaces', projectNamespace);
+    }
+    const baseBranchInput = asString(workspaceRaw['base_branch']);
+    const baseBranch = baseBranchInput && baseBranchInput.trim().length > 0 ? baseBranchInput.trim() : 'main';
+    const workspace = {
+        root: resolvePath(cwd, workspaceRoot),
+        github_repo: githubRepo,
+        base_branch: baseBranch,
+    };
+    // logs (symphony extension): per-issue JSONL run logs.
+    const logsRaw = getObject(raw, 'logs');
+    const logsRootInput = asString(logsRaw['root']);
+    let logsRoot;
+    if (logsRootInput) {
+        const expanded = expandVar(logsRootInput, env);
+        if (expanded === '') {
+            throw new WorkflowError('workflow_parse_error', `logs.root references an unset variable: ${logsRootInput}`);
+        }
+        logsRoot = isAbsolute(expanded) ? expanded : resolvePath(workflowDir, expanded);
+    }
+    else {
+        logsRoot = homeDefaultRoot(env, 'logs', projectNamespace);
+    }
+    const logs = { root: resolvePath(cwd, logsRoot) };
+    // agent (§4.3.4)
+    const agentRaw = getObject(raw, 'agent');
+    const maxTurns = asInt(agentRaw['max_turns'], 20);
+    if (maxTurns <= 0) {
+        throw new WorkflowError('workflow_parse_error', 'agent.max_turns must be positive');
+    }
+    const memAdmissionEnabledRaw = agentRaw['memory_admission_enabled'];
+    const memoryAdmissionEnabled = memAdmissionEnabledRaw === undefined ? true : memAdmissionEnabledRaw !== false;
+    const hostMemoryReserveMib = asInt(agentRaw['host_memory_reserve_mib'], 2048);
+    if (hostMemoryReserveMib < 0) {
+        throw new WorkflowError('workflow_parse_error', 'agent.host_memory_reserve_mib must be a non-negative integer');
+    }
+    const circuitBreakerThreshold = asInt(agentRaw['circuit_breaker_threshold'], 5);
+    if (circuitBreakerThreshold < 0 || circuitBreakerThreshold === 1) {
+        throw new WorkflowError('workflow_parse_error', 'agent.circuit_breaker_threshold must be 0 (disabled) or an integer >= 2');
+    }
+    const agent = {
+        max_concurrent_agents: asInt(agentRaw['max_concurrent_agents'], 10),
+        max_turns: maxTurns,
+        max_retry_backoff_ms: asInt(agentRaw['max_retry_backoff_ms'], 300_000),
+        memory_admission_enabled: memoryAdmissionEnabled,
+        host_memory_reserve_mib: hostMemoryReserveMib,
+        circuit_breaker_threshold: circuitBreakerThreshold,
+    };
+    // acp (Symphony extension; see §4.3.5)
+    const acpRaw = getObject(raw, 'acp');
+    const modelRaw = asString(acpRaw['model']);
+    const modelTrimmed = modelRaw === null ? null : modelRaw.trim();
+    const effortRaw = asString(acpRaw['effort']);
+    const effortTrimmed = effortRaw === null ? null : effortRaw.trim();
+    const acp = {
+        adapter: asString(acpRaw['adapter']) ?? 'claude',
+        model: modelTrimmed && modelTrimmed.length > 0 ? modelTrimmed : null,
+        effort: effortTrimmed && effortTrimmed.length > 0 ? effortTrimmed : null,
+        shell: asString(acpRaw['shell']) ?? 'bash',
+        prompt_timeout_ms: asInt(acpRaw['prompt_timeout_ms'], 3_600_000),
+        read_timeout_ms: asInt(acpRaw['read_timeout_ms'], 30_000),
+        stall_timeout_ms: asInt(acpRaw['stall_timeout_ms'], 300_000),
+        connect_timeout_ms: asInt(acpRaw['connect_timeout_ms'], 30_000),
+        heartbeat_interval_ms: asInt(acpRaw['heartbeat_interval_ms'], 15_000),
+        heartbeat_timeout_ms: asInt(acpRaw['heartbeat_timeout_ms'], 45_000),
+    };
+    // credentials extension (issue 113)
+    const credentialsRaw = getObject(raw, 'credentials');
+    const credentials = {
+        ticker_interval_ms: asInt(credentialsRaw['ticker_interval_ms'], 6 * 60 * 60 * 1000),
+        refresh_margin_ms: asInt(credentialsRaw['refresh_margin_ms'], 5 * 60 * 1000),
+    };
+    // gondolin VM extension
+    const gondolinRaw = getObject(raw, 'gondolin');
+    const volumesRaw = gondolinRaw['volumes'];
+    const volumes = Array.isArray(volumesRaw)
+        ? volumesRaw.flatMap((v) => {
+            if (!v || typeof v !== 'object' || Array.isArray(v))
+                return [];
+            const m = v;
+            const hostRaw = asString(m['host']);
+            const guest = asString(m['guest']);
+            if (!hostRaw || !guest)
+                return [];
+            const expandedHost = expandVar(hostRaw, env);
+            if (expandedHost === '')
+                return [];
+            const host = isAbsolute(expandedHost)
+                ? expandedHost
+                : resolvePath(workflowDir, expandedHost);
+            const readonly = m['readonly'] === true;
+            return [{ host, guest, readonly }];
+        })
+        : [];
+    const ociImageRaw = asString(gondolinRaw['oci_image']);
+    // gondolin.mise (issue 209): mise provisioning is UNCONDITIONAL (issue 233) — the
+    // base image ships only `mise`, so this is the sole toolchain path; only `data_dir`
+    // is configurable. data_dir defaults to a flat, home-based SHARED store
+    // ~/.symphony/mise (NOT per-project — mise dedups installs by tool@version across
+    // VMs). An explicit data_dir resolves like any other root (absolute as-is,
+    // `~`/`$VAR`-expanded, relative → workflowDir). A stale `enabled:` key is simply
+    // ignored (consistent with the parser's unknown-key tolerance), never a hard error.
+    const miseRaw = getObject(gondolinRaw, 'mise');
+    const miseDataDirInput = asString(miseRaw['data_dir']);
+    let miseDataDir;
+    if (miseDataDirInput && miseDataDirInput.trim().length > 0) {
+        const expanded = expandVar(miseDataDirInput.trim(), env);
+        if (expanded === '') {
+            throw new WorkflowError('workflow_parse_error', `gondolin.mise.data_dir references an unset variable: ${miseDataDirInput}`);
+        }
+        miseDataDir = isAbsolute(expanded) ? expanded : resolvePath(workflowDir, expanded);
+    }
+    else {
+        miseDataDir = joinPath(homeDir(env), '.symphony', 'mise');
+    }
+    // gondolin image source precedence (issue 224): explicit `image` > `oci_image` >
+    // managed. `image: managed` is a SENTINEL that selects the managed prebuilt-asset
+    // source (parsed to `managed_image: true` + `image: null` so the sentinel never
+    // reaches `resolveImagePath`). An unset image+oci_image DEFAULTS to managed so a
+    // fresh scaffold is `scaffold → run`. An explicit `image` (escape hatch) or
+    // `oci_image` (auto-convert) keeps `managed_image` false.
+    const rawImage = asString(gondolinRaw['image']);
+    const trimmedImage = rawImage && rawImage.trim().length > 0 ? rawImage.trim() : null;
+    const ociImage = ociImageRaw && ociImageRaw.trim().length > 0 ? ociImageRaw.trim() : null;
+    const managedSentinel = trimmedImage !== null && trimmedImage.toLowerCase() === 'managed';
+    const escapeHatchImage = managedSentinel ? null : trimmedImage;
+    const managedImage = managedSentinel || (escapeHatchImage === null && ociImage === null);
+    const gondolin = {
+        image: escapeHatchImage,
+        managed_image: managedImage,
+        oci_image: ociImage,
+        oci_pull_policy: parseOciPullPolicy(gondolinRaw['oci_pull_policy']),
+        oci_runtime: parseOciRuntime(gondolinRaw['oci_runtime']),
+        cpus: asInt(gondolinRaw['cpus'], 2),
+        mem_mib: asInt(gondolinRaw['mem_mib'], 2048),
+        // rootfs_size (issue 222): the ephemeral mise install lives on the guest rootfs, which
+        // the ~593 MB default is too small for — grow it (qemu size syntax). Default 3G.
+        rootfs_size: nonEmptyOr(asString(gondolinRaw['rootfs_size']), '3G'),
+        volumes,
+        forward_env: asStringList(gondolinRaw['forward_env'], ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY']),
+        guest_agent_path: nonEmptyOr(asString(gondolinRaw['guest_agent_path']), '/opt/symphony/vm-agent.mjs'),
+        node_bin: nonEmptyOr(asString(gondolinRaw['node_bin']), 'node'),
+        mise: { data_dir: miseDataDir },
+    };
+    // egress firewall. mise provisioning is unconditional (issue 233), so when the
+    // workflow declares NO explicit allowed_hosts the default is ALWAYS the mise
+    // provisioning hosts (nodejs.org / npm registry / mise registry) so `mise install`
+    // of the staged SYSTEM config isn't silently firewall-blocked (issue 209). An
+    // explicit `allowed_hosts` REPLACES this default — a consuming repo adding
+    // project-toolchain hosts must re-list the mise ones.
+    const egressRaw = getObject(raw, 'egress');
+    const egress = {
+        allowed_hosts: asStringList(egressRaw['allowed_hosts'], [...MISE_EGRESS_HOSTS]),
+    };
+    // server extension (§9.5)
+    const serverRaw = getObject(raw, 'server');
+    const server = {
+        port: typeof serverRaw['port'] === 'number' ? serverRaw['port'] : null,
+        host: asString(serverRaw['host']) ?? '127.0.0.1',
+    };
+    // mcp extension
+    const mcpRaw = getObject(raw, 'mcp');
+    const mcpEnabledRaw = mcpRaw['enabled'];
+    const mcpEnabled = mcpEnabledRaw === undefined ? true : mcpEnabledRaw !== false;
+    const mcp = {
+        enabled: mcpEnabled,
+        host: asString(mcpRaw['host']) ?? '127.0.0.1',
+        explicit_host_url: asString(mcpRaw['host_url']),
+    };
+    // pr (issue 38, slimmed in issue 139)
+    const prRaw = getObject(raw, 'pr');
+    const pr = {
+        enabled: prRaw['enabled'] === true,
+        poll_interval_ms: asInt(prRaw['poll_interval_ms'], 30_000),
+    };
+    if (pr.poll_interval_ms < 0) {
+        throw new WorkflowError('workflow_parse_error', 'pr.poll_interval_ms must be non-negative');
+    }
+    const config = {
+        workflow_path: workflowAbs,
+        workflow_dir: workflowDir,
+        tracker,
+        prompt,
+        polling,
+        workspace,
+        logs,
+        agent,
+        acp,
+        gondolin,
+        egress,
+        server,
+        mcp,
+        pr,
+        credentials,
+        states,
+    };
+    return { config };
+}
+// ─── per-state spawn block (recurring reflection spawn) ───────────────────────
+function parseStateSpawnBlock(stateName, raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": spawn must be a map (on_idle / after_terminal / title / body / max_in_flight)`);
+    }
+    const m = raw;
+    const afterTerminal = asInt(m['after_terminal'], 0);
+    if (afterTerminal < 0) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": spawn.after_terminal must be a non-negative integer (0 disables the terminal-count trigger)`);
+    }
+    const maxInFlight = asInt(m['max_in_flight'], 1);
+    if (maxInFlight < 1) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": spawn.max_in_flight must be a positive integer (>= 1)`);
+    }
+    const titleRaw = asString(m['title']);
+    const title = titleRaw && titleRaw.trim().length > 0 ? titleRaw.trim() : 'Reflection {{ stamp }}';
+    const bodyRaw = asString(m['body']);
+    const body = bodyRaw && bodyRaw.trim().length > 0 ? bodyRaw.trim() : null;
+    return {
+        on_idle: m['on_idle'] === true,
+        after_terminal: afterTerminal,
+        title,
+        body,
+        max_in_flight: maxInFlight,
+    };
+}
+// ─── states block (§4.3, mandatory) ──────────────────────────────────────────
+function parseStatesBlock(raw, parseActions) {
+    if (raw === undefined || raw === null) {
+        throw new WorkflowError('workflow_parse_error', 'workflow YAML must declare a top-level `states:` block with at least one active, one terminal, and one holding state. See WORKFLOW.template.yaml for the schema.');
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new WorkflowError('workflow_parse_error', 'states: must be a map of name → config');
+    }
+    const entries = Object.entries(raw);
+    if (entries.length === 0) {
+        throw new WorkflowError('workflow_parse_error', 'workflow YAML `states:` block is empty; declare at least one active, one terminal, and one holding state. See WORKFLOW.template.yaml for the schema.');
+    }
+    const out = {};
+    for (const [name, value] of entries) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new WorkflowError('workflow_parse_error', `state "${name}": value must be a map`);
+        }
+        const m = value;
+        const roleRaw = asString(m['role']);
+        if (roleRaw !== 'active' && roleRaw !== 'terminal' && roleRaw !== 'holding') {
+            throw new WorkflowError('workflow_parse_error', `state "${name}": role must be one of active|terminal|holding (got: ${String(m['role'])})`);
+        }
+        const adapter = asString(m['adapter']);
+        const modelRaw = asString(m['model']);
+        const modelTrimmed = modelRaw === null ? undefined : modelRaw.trim();
+        const model = modelTrimmed === undefined ? undefined : modelTrimmed.length > 0 ? modelTrimmed : null;
+        const effortRaw = asString(m['effort']);
+        const effortTrimmed = effortRaw === null ? undefined : effortRaw.trim();
+        const effort = effortTrimmed === undefined ? undefined : effortTrimmed.length > 0 ? effortTrimmed : null;
+        let maxTurns;
+        if (m['max_turns'] !== undefined) {
+            const n = asInt(m['max_turns'], -1);
+            if (n <= 0) {
+                throw new WorkflowError('workflow_parse_error', `state "${name}": max_turns must be a positive integer`);
+            }
+            maxTurns = n;
+        }
+        let maxConcurrent;
+        if (m['max_concurrent'] !== undefined) {
+            const n = asInt(m['max_concurrent'], -1);
+            if (n <= 0) {
+                throw new WorkflowError('workflow_parse_error', `state "${name}": max_concurrent must be a positive integer`);
+            }
+            maxConcurrent = n;
+        }
+        let allowed;
+        if (m['allowed_transitions'] === undefined) {
+            allowed = undefined;
+        }
+        else if (m['allowed_transitions'] === null) {
+            allowed = null;
+        }
+        else if (Array.isArray(m['allowed_transitions'])) {
+            allowed = m['allowed_transitions'].filter((x) => typeof x === 'string');
+        }
+        else {
+            throw new WorkflowError('workflow_parse_error', `state "${name}": allowed_transitions must be a list of state names (or null/omitted)`);
+        }
+        const stateActions = parseActions(name, m['actions']);
+        const evalModeRaw = m['eval_mode'];
+        if (evalModeRaw !== undefined && typeof evalModeRaw !== 'boolean') {
+            throw new WorkflowError('workflow_parse_error', `state "${name}": eval_mode must be a boolean (true/false)`);
+        }
+        const statePr = parseStatePrBlock(name, m['pr']);
+        const stateSpawn = parseStateSpawnBlock(name, m['spawn']);
+        const promptFileRaw = asString(m['prompt_file']);
+        const sc = { role: roleRaw };
+        if (adapter !== null)
+            sc.adapter = adapter;
+        // Stored as the raw (trimmed) string here; buildServiceConfig resolves it to
+        // an absolute path against the workflow dir (it owns the env + path helpers).
+        if (promptFileRaw && promptFileRaw.trim().length > 0)
+            sc.prompt_file = promptFileRaw.trim();
+        if (model !== undefined)
+            sc.model = model;
+        if (effort !== undefined)
+            sc.effort = effort;
+        if (maxTurns !== undefined)
+            sc.max_turns = maxTurns;
+        if (maxConcurrent !== undefined)
+            sc.max_concurrent = maxConcurrent;
+        if (allowed !== undefined)
+            sc.allowed_transitions = allowed;
+        if (stateActions !== undefined)
+            sc.actions = stateActions;
+        if (evalModeRaw === true)
+            sc.eval_mode = true;
+        if (statePr !== undefined)
+            sc.pr = statePr;
+        if (stateSpawn !== undefined)
+            sc.spawn = stateSpawn;
+        out[name] = sc;
+    }
+    return out;
+}
+// ─── per-state pr block (issue 139) ────────────────────────────────────────────
+function parseStatePrBlock(stateName, raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": pr must be a map (auto_merge / on_conflict / close)`);
+    }
+    const m = raw;
+    const out = {};
+    if (m['auto_merge'] !== undefined && m['auto_merge'] !== null) {
+        const s = asString(m['auto_merge']);
+        if (s !== 'squash' && s !== 'merge' && s !== 'rebase') {
+            throw new WorkflowError('workflow_parse_error', `state "${stateName}": pr.auto_merge must be one of squash|merge|rebase`);
+        }
+        out.auto_merge = s;
+    }
+    if (m['on_conflict'] !== undefined && m['on_conflict'] !== null) {
+        const oc = m['on_conflict'];
+        if (typeof oc !== 'object' || Array.isArray(oc)) {
+            throw new WorkflowError('workflow_parse_error', `state "${stateName}": pr.on_conflict must be a map with a route_to field`);
+        }
+        const routeTo = asString(oc['route_to']);
+        if (!routeTo || routeTo.trim().length === 0) {
+            throw new WorkflowError('workflow_parse_error', `state "${stateName}": pr.on_conflict.route_to must be a non-empty state name`);
+        }
+        out.on_conflict = { route_to: routeTo.trim() };
+    }
+    if (m['close'] !== undefined && m['close'] !== null) {
+        if (typeof m['close'] !== 'boolean') {
+            throw new WorkflowError('workflow_parse_error', `state "${stateName}": pr.close must be a boolean`);
+        }
+        if (m['close'] === true)
+            out.close = true;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+//# sourceMappingURL=parse.js.map