smol-symphony 0.1.0 → 0.2.0

package/dist/workflow.js

@@ -1,72 +1,45 @@
-// WORKFLOW.md loader, watcher, and typed config view (SPEC §5, §6).
-import { readFile } from 'node:fs/promises';
-import { existsSync, statSync } from 'node:fs';
+// WORKFLOW.md parser and typed config view (SPEC §4). Pure: no fs, no process.
+// The on-disk read and watcher live in `./workflow-loader.ts` (shell).
 import path from 'node:path';
 import os from 'node:os';
-import chokidar from 'chokidar';
-import { parse as parseYaml } from 'yaml';
+import { parseFrontMatter, FrontMatterError } from './util/frontmatter.js';
+import { isKnownAdapter } from './agent/adapter-names.js';
+import { parseActionsBlock } from './actions/parsing.js';
+import { WorkflowError } from './errors.js';
 import { log } from './logging.js';
-import { isKnownAdapter } from './agent/adapters.js';
-export class WorkflowError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'WorkflowError';
-    }
-}
-// §5.2: split YAML front matter from prompt body.
+export { WorkflowError };
+// §4.2: split YAML front matter from prompt body. Thin wrapper over the shared
+// parser that translates FrontMatterError → WorkflowError so callers keep
+// matching on the existing error codes.
 export function splitFrontMatter(text) {
-    if (!text.startsWith('---')) {
-        return { config: {}, body: text.trim() };
-    }
-    const lines = text.split(/\r?\n/);
-    // First and closing fences must be exactly `---` (with optional trailing whitespace),
-    // unindented. Otherwise an indented `---` inside a multiline YAML hook script would be
-    // mistaken for the closing fence.
-    const isFence = (line) => /^---\s*$/.test(line ?? '');
-    if (!isFence(lines[0])) {
-        return { config: {}, body: text.trim() };
-    }
-    let endIdx = -1;
-    for (let i = 1; i < lines.length; i++) {
-        if (isFence(lines[i])) {
-            endIdx = i;
-            break;
-        }
-    }
-    if (endIdx < 0) {
-        throw new WorkflowError('workflow_parse_error', 'unterminated YAML front matter');
-    }
-    const fmText = lines.slice(1, endIdx).join('\n');
-    const body = lines.slice(endIdx + 1).join('\n').trim();
-    let parsed;
+    let fm;
     try {
-        parsed = fmText.trim().length === 0 ? {} : parseYaml(fmText);
+        fm = parseFrontMatter(text);
     }
     catch (err) {
-        throw new WorkflowError('workflow_parse_error', `invalid YAML front matter: ${err.message}`);
-    }
-    if (parsed === null || parsed === undefined)
-        parsed = {};
-    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new WorkflowError('workflow_front_matter_not_a_map', 'YAML front matter must decode to a map');
+        if (err instanceof FrontMatterError) {
+            const code = err.code === 'not_a_map' ? 'workflow_front_matter_not_a_map' : 'workflow_parse_error';
+            throw new WorkflowError(code, err.message);
+        }
+        throw err;
     }
-    return { config: parsed, body };
+    return { config: fm.fields, body: fm.body };
 }
-export async function loadWorkflow(workflowPath) {
-    let text;
-    try {
-        text = await readFile(workflowPath, 'utf8');
-    }
-    catch (err) {
-        throw new WorkflowError('missing_workflow_file', `cannot read ${workflowPath}: ${err.message}`);
-    }
-    const { config, body } = splitFrontMatter(text);
-    return { config, prompt_template: body };
+/**
+ * Pure entry point: split front matter, build the typed view, and return both
+ * shapes. The shell loader reads the file from disk and the operator's env,
+ * then calls this. `env` defaults to an empty map so tests that do not exercise
+ * `$VAR` expansion need not thread it through.
+ */
+export function parseWorkflow(text, workflowPath, env = {}) {
+    const { config: raw, body } = splitFrontMatter(text);
+    const definition = { config: raw, prompt_template: body };
+    const config = buildServiceConfig(raw, workflowPath, env);
+    return { definition, config };
 }
-// $VAR / ~ expansion for path/command fields (§6.1).
-export function expandVar(value) {
+// $VAR / ~ expansion for path/command fields. `env` carries the variable map
+// (the shell loader passes process.env; tests pass an explicit shape).
+export function expandVar(value, env = {}) {
     if (typeof value !== 'string')
         return value;
     let s = value;
@@ -75,7 +48,7 @@ export function expandVar(value) {
     }
     const m = s.match(/^\$([A-Z_][A-Z0-9_]*)$/);
     if (m) {
-        const envVal = process.env[m[1]];
+        const envVal = env[m[1]];
         return envVal ?? '';
     }
     return s;
@@ -97,38 +70,53 @@ function asStringList(v, fallback) {
         return v.filter((x) => typeof x === 'string');
     return fallback;
 }
-function asMapStrPosInt(v) {
-    const out = {};
-    if (v && typeof v === 'object' && !Array.isArray(v)) {
-        for (const [k, raw] of Object.entries(v)) {
-            const n = asInt(raw, 0);
-            if (n > 0)
-                out[k.toLowerCase()] = n;
-        }
-    }
-    return out;
-}
 function getObject(parent, key) {
     const v = parent[key];
     if (v && typeof v === 'object' && !Array.isArray(v))
         return v;
     return {};
 }
-// Build a fully typed ServiceConfig from a parsed front matter map (§6.1).
-export function buildServiceConfig(raw, workflowPath) {
+// workspace.github_repo: a GitHub `owner/repo` slug that enables push/PR mode,
+// or null for local-only. There is no auto-detection — the value is either
+// absent (local-only) or a literal slug. Empty string / "none"
+// (case-insensitive) normalize to null so an operator can disable push mode
+// without deleting the key. Any other value MUST be a GitHub owner/repo slug:
+// `owner` is GitHub's `[alnum]`/`-` charset (no `.`, `:`, `@`, scheme, or host)
+// and `repo` is `[alnum]`/`.`/`_`/`-`. This rejects whole-URL and SSH-style
+// remotes (`https://github.com/foo/bar`, `git@github.com:foo/bar`) and bare
+// names (`foo`) at parse time, so a typo can't slip through and build a broken
+// `https://github.com/<garbage>.git` origin that fails later during setup.
+// Takes the raw YAML value (not asString'd) so a present-but-wrong-type value
+// (`github_repo: true`, `123`, `{}`) is rejected rather than coerced to null —
+// otherwise the fail-fast contract has a hole that silently disables push/PR.
+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;
+}
+// Build a fully typed ServiceConfig from a parsed front matter map. `env`
+// supplies the variable map for `$VAR` expansion; defaults to {} so pure
+// callers don't need to thread one in.
+export function buildServiceConfig(raw, workflowPath, env = {}) {
     const workflowAbs = path.resolve(workflowPath);
     const workflowDir = path.dirname(workflowAbs);
-    // tracker (§5.3.1)
+    // tracker (§4.3.1)
     const trackerRaw = getObject(raw, 'tracker');
     const trackerKind = (asString(trackerRaw['kind']) ?? '').trim();
-    const apiKeyRaw = asString(trackerRaw['api_key']);
-    const apiKeyResolved = apiKeyRaw ? expandVar(apiKeyRaw) : null;
-    const trackerEndpointDefault = trackerKind === 'linear' ? 'https://api.linear.app/graphql' : null;
     // local-tracker extension: optional `tracker.root` path.
     const trackerRootRaw = asString(trackerRaw['root']);
     let trackerRoot = null;
     if (trackerRootRaw) {
-        const expanded = expandVar(trackerRootRaw);
+        const expanded = expandVar(trackerRootRaw, env);
         if (expanded === '') {
             throw new WorkflowError('workflow_parse_error', `tracker.root references an unset variable: ${trackerRootRaw}`);
         }
@@ -138,32 +126,23 @@ export function buildServiceConfig(raw, workflowPath) {
         // Default local tracker root: <workflow-dir>/issues
         trackerRoot = path.resolve(workflowDir, 'issues');
     }
+    const states = parseStatesBlock(raw['states']);
     const tracker = {
         kind: trackerKind,
-        endpoint: asString(trackerRaw['endpoint']) ?? trackerEndpointDefault,
-        api_key: apiKeyResolved && apiKeyResolved.length > 0 ? apiKeyResolved : null,
-        project_slug: asString(trackerRaw['project_slug']),
-        active_states: asStringList(trackerRaw['active_states'], ['Todo', 'In Progress']),
-        terminal_states: asStringList(trackerRaw['terminal_states'], [
-            'Closed',
-            'Cancelled',
-            'Canceled',
-            'Duplicate',
-            'Done',
-        ]),
+        states,
         root: trackerRoot,
     };
-    // polling (§5.3.2)
+    // polling (§4.3.2)
     const pollingRaw = getObject(raw, 'polling');
     const polling = {
         interval_ms: asInt(pollingRaw['interval_ms'], 30_000),
     };
-    // workspace (§5.3.3)
+    // workspace (§4.3.3)
     const workspaceRaw = getObject(raw, 'workspace');
     const wsRootInput = asString(workspaceRaw['root']);
     let workspaceRoot;
     if (wsRootInput) {
-        const expanded = expandVar(wsRootInput);
+        const expanded = expandVar(wsRootInput, env);
         if (expanded === '') {
             throw new WorkflowError('workflow_parse_error', `workspace.root references an unset variable: ${wsRootInput}`);
         }
@@ -172,58 +151,108 @@ export function buildServiceConfig(raw, workflowPath) {
     else {
         workspaceRoot = path.join(os.tmpdir(), 'symphony_workspaces');
     }
-    const workspace = { root: path.resolve(workspaceRoot) };
-    // hooks (§5.3.4)
-    const hooksRaw = getObject(raw, 'hooks');
-    const hooks = {
-        after_create: asString(hooksRaw['after_create']),
-        before_run: asString(hooksRaw['before_run']),
-        after_run: asString(hooksRaw['after_run']),
-        before_remove: asString(hooksRaw['before_remove']),
-        timeout_ms: asInt(hooksRaw['timeout_ms'], 60_000),
+    const baseBranchInput = asString(workspaceRaw['base_branch']);
+    const baseBranch = baseBranchInput && baseBranchInput.trim().length > 0 ? baseBranchInput.trim() : 'main';
+    const workspace = {
+        root: path.resolve(workspaceRoot),
+        github_repo: parseGithubRepo(workspaceRaw['github_repo']),
+        base_branch: baseBranch,
     };
-    if (hooks.timeout_ms <= 0) {
-        throw new WorkflowError('workflow_parse_error', 'hooks.timeout_ms must be positive');
+    // logs (symphony extension): per-issue JSONL run logs. Default sits next to the workspace
+    // root under `.symphony/logs/` so all symphony-managed state for a project lives in one
+    // tree. Same expansion rules as workspace.root.
+    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 = path.isAbsolute(expanded) ? expanded : path.resolve(workflowDir, expanded);
+    }
+    else {
+        logsRoot = path.resolve(workflowDir, '.symphony', 'logs');
     }
-    // agent (§5.3.5)
+    const logs = { root: path.resolve(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');
     }
+    // Memory-aware admission cap (issue 27). Default-on with a 2 GiB host reserve — that's
+    // enough headroom for the orchestrator process, the per-VM Gondolin runners,
+    // and the kernel's working set on a typical workstation. Operators can disable the cap (set
+    // `memory_admission_enabled: false`) on hosts that don't expose /proc/meminfo or where
+    // the static cap is already the binding constraint.
+    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');
+    }
+    // Circuit breaker (issue 128). Default 5: after five consecutive identical
+    // failures the orchestrator stops retrying and routes the issue to a holding
+    // state. 0 disables the breaker; 1 would trip on the first failure (no retry
+    // ever), which is rarely wanted, so the parser rejects it as a likely
+    // misconfiguration — use 0 to disable or >= 2 to bound the loop.
+    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),
-        max_concurrent_agents_by_state: asMapStrPosInt(agentRaw['max_concurrent_agents_by_state']),
+        memory_admission_enabled: memoryAdmissionEnabled,
+        host_memory_reserve_mib: hostMemoryReserveMib,
+        circuit_breaker_threshold: circuitBreakerThreshold,
     };
-    // acp (Symphony extension; supersedes the §5.3.6 `codex` block). `adapter` selects
-    // one of symphony's known profiles (claude, codex). `command` is optional: when
-    // null/unset, symphony auto-derives the launch command from the adapter profile and
-    // stages the host credential file into the workspace. Override `command` only if
-    // you need a custom launch (testing a forked adapter, a non-default binary path,
-    // etc.) — overriding also opts out of credential staging.
+    // acp (Symphony extension; see §4.3.5). `adapter` selects
+    // one of symphony's known profiles (claude, codex, opencode); symphony auto-derives the
+    // launch command from the adapter profile. Credentials are NOT staged into the workspace:
+    // the guest only ever holds a token-shaped placeholder, and the host substitutes the real
+    // upstream token into the outbound request at Gondolin egress (TLS-MITM via
+    // `createHttpHooks` in src/agent/credential-secrets.ts). The real host credential
+    // (`~/.claude/.credentials.json` for claude; `~/.codex/auth.json` access token or
+    // `OPENAI_API_KEY` for codex; the GitHub Copilot token exchanged from
+    // `~/.local/share/opencode/auth.json` for opencode) never enters the VM.
+    //
+    // `acp.bridge` configures the host-side TCP listener that the in-VM agent dials back
+    // to for ACP traffic. The bridge replaced the earlier in-VM-exec stdio path; see
+    // src/acp-bridge.ts for rationale.
     const acpRaw = getObject(raw, 'acp');
+    const bridgeRaw = getObject(acpRaw, 'bridge');
+    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',
-        command: asString(acpRaw['command']),
+        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),
+        bridge: {
+            bind_host: asString(bridgeRaw['bind_host']) ?? '0.0.0.0',
+            bind_port: asInt(bridgeRaw['bind_port'], 8788),
+            reach_host: asString(bridgeRaw['reach_host']) ?? '127.0.0.1',
+            reach_url: asString(bridgeRaw['reach_url']),
+            connect_timeout_ms: asInt(bridgeRaw['connect_timeout_ms'], 30_000),
+        },
     };
-    // smolvm extension
-    const smolvmRaw = getObject(raw, 'smolvm');
-    const fromRaw = asString(smolvmRaw['from']);
-    let from = null;
-    if (fromRaw) {
-        const expanded = expandVar(fromRaw);
-        if (expanded === '') {
-            throw new WorkflowError('workflow_parse_error', `smolvm.from references an unset variable: ${fromRaw}`);
-        }
-        from = path.isAbsolute(expanded) ? expanded : path.resolve(workflowDir, expanded);
-    }
-    const volumesRaw = smolvmRaw['volumes'];
+    // credentials extension (issue 113). Defaults work out of the box for the
+    // common case: run the host ticker every 6 hours.
+    const credentialsRaw = getObject(raw, 'credentials');
+    const credentials = {
+        ticker_interval_ms: asInt(credentialsRaw['ticker_interval_ms'], 6 * 60 * 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))
@@ -233,7 +262,7 @@ export function buildServiceConfig(raw, workflowPath) {
             const guest = asString(m['guest']);
             if (!hostRaw || !guest)
                 return [];
-            const expandedHost = expandVar(hostRaw);
+            const expandedHost = expandVar(hostRaw, env);
             if (expandedHost === '')
                 return [];
             const host = path.isAbsolute(expandedHost)
@@ -243,32 +272,38 @@ export function buildServiceConfig(raw, workflowPath) {
             return [{ host, guest, readonly }];
         })
         : [];
-    const smolvm = {
-        image: asString(smolvmRaw['image']),
-        from,
-        cpus: asInt(smolvmRaw['cpus'], 2),
-        mem_mib: asInt(smolvmRaw['mem_mib'], 2048),
-        net: smolvmRaw['net'] !== false,
-        bin_path: asString(smolvmRaw['bin_path']),
+    const gondolin = {
+        image: asString(gondolinRaw['image']),
+        cpus: asInt(gondolinRaw['cpus'], 2),
+        mem_mib: asInt(gondolinRaw['mem_mib'], 2048),
         volumes,
-        // Default forwarded credentials cover all three shipped ACP adapters so workflows that
-        // do not override `smolvm.forward_env` still authenticate after the default-adapter
-        // switch to claude-agent-acp.
-        forward_env: asStringList(smolvmRaw['forward_env'], [
+        // `forward_env` is forwarded into the VM boot env, but the runner strips EVERY
+        // credential-bearing var (`stripCredentialEnv`) before boot — the guest holds
+        // only the token-shaped placeholder Gondolin substitutes at egress, never a real
+        // key. So even if an operator lists `OPENAI_API_KEY` here, it never reaches a VM.
+        // The defaults are retained for any future forward-env-strategy adapter.
+        forward_env: asStringList(gondolinRaw['forward_env'], [
             'OPENAI_API_KEY',
             'ANTHROPIC_API_KEY',
         ]),
-        endpoint: asString(smolvmRaw['endpoint']) ??
-            `unix://${process.env.XDG_RUNTIME_DIR ?? '/run/user/1000'}/smolvm.sock`,
     };
-    // server extension (§13.7)
+    // egress firewall: the general dev-tooling allowlist the in-VM agent may reach
+    // (npm/git/CDNs) for gates. DISTINCT from the credential layer's per-adapter
+    // substitution hosts — nothing listed here ever gets a real token substituted
+    // (see credential-secrets.ts buildAdapterHooksConfig). Empty default: the agent
+    // can reach only each adapter's inference host until the operator opts hosts in.
+    const egressRaw = getObject(raw, 'egress');
+    const egress = {
+        allowed_hosts: asStringList(egressRaw['allowed_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: per-issue MCP server (mark_done + request_human_steering tools) injected
-    // into each ACP session. `host` defaults to the QEMU slirp gateway; the port is the
+    // mcp extension: per-issue MCP server (transition + request_human_steering + propose_issue
+    // tools) injected into each ACP session. `host` defaults to the QEMU slirp gateway; the port is the
     // actually-bound HTTP server's port (resolved at runtime, not config-parse time, so
     // `--port` and an unset server.port can never desync). `host_url` is an explicit full-URL
     // override for cases where the VM can't reach the orchestrator via the host gateway.
@@ -277,109 +312,511 @@ export function buildServiceConfig(raw, workflowPath) {
     const mcpEnabled = mcpEnabledRaw === undefined ? true : mcpEnabledRaw !== false;
     const mcp = {
         enabled: mcpEnabled,
-        // 127.0.0.1 works for smolvm because its VM network intercepts loopback
-        // traffic and forwards it to the host's loopback. (Empirically verified;
+        // 127.0.0.1 works because Gondolin maps a synthetic guest host to the host's
+        // loopback (`tcp.hosts`). (Empirically verified;
         // 10.0.2.2 — the QEMU slirp gateway — is NOT reachable here.) Other VMMs
         // can override via the `host` field in the WORKFLOW.md mcp block.
         host: asString(mcpRaw['host']) ?? '127.0.0.1',
         explicit_host_url: asString(mcpRaw['host_url']),
     };
+    // pr (issue 38, slimmed in issue 139). Optional block; default off. The slim
+    // host-global engine toggle: `pr: { enabled, poll_interval_ms }`. The
+    // merge/close/route targets and auto-merge strategy live ON the terminal
+    // states they describe (`states.<name>.pr`, parsed in parseStatesBlock) and
+    // are derived by scanning states (`derivePrRouting`), never named here.
+    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');
+    }
+    // sleep_cycle (issue 125; retired in issue 140). The auto-arm trigger moved
+    // ONTO the active state it arms (`states.<name>.arm`, parsed in
+    // parseStatesBlock). A legacy top-level `sleep_cycle:` block is folded onto the
+    // reflect_state it named (foldLegacySleepCycle) for one release with a
+    // deprecation warning; there is no top-level sleep-cycle field on the resulting
+    // ServiceConfig anymore — the orchestrator derives the armed state by scanning
+    // states (`deriveArmRouting`).
+    foldLegacySleepCycle(states, getObject(raw, 'sleep_cycle'), Object.prototype.hasOwnProperty.call(raw, 'sleep_cycle'));
     return {
         workflow_path: workflowAbs,
         workflow_dir: workflowDir,
         tracker,
         polling,
         workspace,
-        hooks,
+        logs,
         agent,
         acp,
-        smolvm,
+        gondolin,
+        egress,
         server,
         mcp,
+        pr,
+        credentials,
+        states,
     };
 }
-// §6.3 dispatch preflight validation.
-export function validateDispatch(cfg) {
-    if (!cfg.tracker.kind)
-        return 'tracker.kind is required';
-    if (cfg.tracker.kind !== 'linear' && cfg.tracker.kind !== 'local') {
-        return `unsupported_tracker_kind: ${cfg.tracker.kind}`;
-    }
-    if (cfg.tracker.kind === 'linear') {
-        if (!cfg.tracker.api_key)
-            return 'missing_tracker_api_key';
-        if (!cfg.tracker.project_slug)
-            return 'missing_tracker_project_slug';
-    }
-    if (cfg.tracker.kind === 'local') {
-        if (!cfg.tracker.root)
-            return 'tracker.root must be set for local tracker';
-        if (!existsSync(cfg.tracker.root) || !statSync(cfg.tracker.root).isDirectory()) {
-            return `tracker.root not found or not a directory: ${cfg.tracker.root}`;
+/**
+ * Per-state `arm:` block (issue 140). Optional, valid on an active state.
+ * `issue` is the recurring issue armed into this state; `from` the holding state
+ * it rests in between runs; `on_idle` / `after_terminal` are the two triggers.
+ * The structural shape (types, `from` non-empty, `after_terminal` non-negative)
+ * is validated here; the cross-reference (arm only on active states, `from` is a
+ * declared holding state, `issue` required, at most one armed state) lives in
+ * `validateStates`. Returns `undefined` when the block is absent. `on_idle`
+ * defaults to false (opt-in, symmetric with `after_terminal: 0`).
+ */
+function parseStateArmBlock(stateName, raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": arm must be a map (issue / from / on_idle / after_terminal)`);
+    }
+    const m = raw;
+    const issueRaw = asString(m['issue']);
+    const issue = issueRaw && issueRaw.trim().length > 0 ? issueRaw.trim() : null;
+    const fromRaw = asString(m['from']);
+    if (!fromRaw || fromRaw.trim().length === 0) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": arm.from must be a non-empty holding state name`);
+    }
+    const afterTerminal = asInt(m['after_terminal'], 0);
+    if (afterTerminal < 0) {
+        throw new WorkflowError('workflow_parse_error', `state "${stateName}": arm.after_terminal must be a non-negative integer (0 disables the terminal-count trigger)`);
+    }
+    return {
+        issue,
+        from: fromRaw.trim(),
+        on_idle: m['on_idle'] === true,
+        after_terminal: afterTerminal,
+    };
+}
+export function deriveArmRouting(states) {
+    for (const [name, sc] of Object.entries(states)) {
+        if (sc.role !== 'active' || !sc.arm)
+            continue;
+        return {
+            armState: name,
+            issue: sc.arm.issue,
+            from: sc.arm.from,
+            onIdle: sc.arm.on_idle,
+            afterTerminal: sc.arm.after_terminal,
+        };
+    }
+    return { armState: null, issue: null, from: null, onIdle: false, afterTerminal: 0 };
+}
+/**
+ * Fold a deprecated top-level `sleep_cycle:` block onto the active state it named
+ * (issue 140). Mirrors the now-removed legacy PR-autopilot fold: the trigger
+ * that used to live as named strings (`reflect_state` / `dormant_state` / `issue_id` /
+ * `arm_on_idle` / `arm_after_done`) is injected onto the reflect_state's `arm:`
+ * field so the state scan (`deriveArmRouting`) is the single runtime source of
+ * truth. A state that already declares `arm:` wins on conflict. Emits one
+ * deprecation warning whenever the block is present. Only folds when the legacy
+ * block is `enabled: true` — in the new model declaring `arm:` IS the enable, so
+ * a disabled legacy block produces no arm. The legacy `arm_on_idle` default of
+ * true is preserved (`!== false`). A `reflect_state` matching no declared state
+ * is a silent no-op (the warning already points at the new shape).
+ */
+function foldLegacySleepCycle(states, legacyRaw, present) {
+    if (!present)
+        return;
+    log.warn('sleep_cycle: is deprecated; declare the auto-arm trigger on the active state it arms as `states.<name>.arm` (issue / from / on_idle / after_terminal)', {});
+    // Preserve the original sleep-cycle parser's non-negative validation: a
+    // negative `arm_after_done` was a parse error, not a silent disable. Validated
+    // whenever the block is present (independent of `enabled`), matching the
+    // retired `validateSleepCycle` and the new `arm.after_terminal` parser.
+    const afterTerminal = asInt(legacyRaw['arm_after_done'], 0);
+    if (afterTerminal < 0) {
+        throw new WorkflowError('workflow_parse_error', 'sleep_cycle.arm_after_done must be a non-negative integer (0 disables the terminal-count trigger)');
+    }
+    if (legacyRaw['enabled'] !== true)
+        return;
+    const reflectRaw = asString(legacyRaw['reflect_state']);
+    const reflectState = reflectRaw && reflectRaw.trim().length > 0 ? reflectRaw.trim() : 'Reflect';
+    const dormantRaw = asString(legacyRaw['dormant_state']);
+    const dormantState = dormantRaw && dormantRaw.trim().length > 0 ? dormantRaw.trim() : 'Dormant';
+    const issueRaw = asString(legacyRaw['issue_id']);
+    const issue = issueRaw && issueRaw.trim().length > 0 ? issueRaw.trim() : null;
+    injectStateArm(states, reflectState, {
+        issue,
+        from: dormantState,
+        on_idle: legacyRaw['arm_on_idle'] !== false,
+        after_terminal: afterTerminal,
+    });
+}
+/**
+ * Inject a derived `arm:` block onto the (case-insensitively) named active state,
+ * but only when that state declares no `arm:` of its own — state-level config
+ * always wins over a folded legacy value. No-op when the name matches no state.
+ */
+function injectStateArm(states, name, arm) {
+    const lower = name.toLowerCase();
+    for (const [stateName, sc] of Object.entries(states)) {
+        if (stateName.toLowerCase() !== lower)
+            continue;
+        if (sc.arm)
+            return;
+        sc.arm = arm;
+        return;
+    }
+}
+// Parse the top-level `states:` block. The block is mandatory: every workflow
+// must declare at least one `active`, one `terminal`, and one `holding` state
+// (validation happens in `validateStates`). Insertion order matters —
+// downstream consumers (dashboard, role-filtered active/terminal listings)
+// follow declaration order — so we build a plain object incrementally rather
+// than reconstructing via `Object.fromEntries`.
+function parseStatesBlock(raw) {
+    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.md 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.md 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;
+        // Same undefined-vs-null semantics as `model`: a missing key inherits the
+        // workflow-level `acp.effort`; a blank/whitespace string normalizes to null
+        // (an explicit "use the adapter default for this state" signal).
+        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;
+        }
+        // Per-state concurrency cap (issue 137) — same positive-integer validation
+        // as max_turns. Undefined when omitted (no per-state cap; only the global
+        // agent.max_concurrent_agents ceiling applies).
+        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 = parseActionsBlock(name, m['actions']);
+        // eval_mode is a strict boolean opt-in: only true enables it, any other
+        // value (including undefined, null, "true" string) leaves it off. Strict
+        // typing here matches the rest of the YAML-flag plumbing in the parser
+        // and stops a YAML-quoting accident ("true") from silently enabling the
+        // mounts.
+        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 stateArm = parseStateArmBlock(name, m['arm']);
+        const sc = { role: roleRaw };
+        if (adapter !== null)
+            sc.adapter = adapter;
+        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 (stateArm !== undefined)
+            sc.arm = stateArm;
+        out[name] = sc;
+    }
+    return out;
+}
+/**
+ * Per-state `pr:` block (issue 139). Optional, valid on a terminal state.
+ * `auto_merge` (squash|merge|rebase) marks the merge state and picks the
+ * `gh pr merge --auto` strategy; `on_conflict.route_to` names the active state
+ * a non-mergeable PR is routed back into; `close: true` marks the close state.
+ * Returns `undefined` when the block is absent or declares nothing meaningful
+ * (so an empty `pr: {}` doesn't shadow a legacy fold). The structural shape is
+ * validated here; the cross-reference (route_to is a declared state, pr only on
+ * terminal states, merge/close uniqueness) is in `validateStates`.
+ */
+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;
+}
+export function derivePrRouting(states) {
+    let mergeState = null;
+    let closeState = null;
+    let conflictRouteTo = null;
+    let strategy = 'squash';
+    for (const [name, sc] of Object.entries(states)) {
+        if (sc.role !== 'terminal' || !sc.pr)
+            continue;
+        if (sc.pr.auto_merge && mergeState === null) {
+            mergeState = name;
+            strategy = sc.pr.auto_merge;
+            conflictRouteTo = sc.pr.on_conflict?.route_to ?? null;
+        }
+        if (sc.pr.close && closeState === null) {
+            closeState = name;
         }
     }
-    // When acp.command is explicitly set, the operator owns the launch (and credential
-    // staging). Otherwise the adapter id must be one symphony has a profile for, so
-    // the runner can auto-derive the command and ship credentials.
-    if (cfg.acp.command !== null) {
-        if (!cfg.acp.command.trim())
-            return 'acp.command must be non-empty when set';
+    return { mergeState, closeState, conflictRouteTo, strategy };
+}
+/**
+ * Resolve the typed action list a given state should run on transition-in.
+ * Case-insensitive state lookup; returns the parsed `WorkflowAction[]` (or
+ * undefined when the state has no actions block). The runner consults this on
+ * transition into a terminal state to drive the push/PR handoff.
+ */
+export function resolveActionsForState(cfg, stateName) {
+    const states = cfg.states;
+    let key = null;
+    if (Object.prototype.hasOwnProperty.call(states, stateName)) {
+        key = stateName;
     }
-    else if (!isKnownAdapter(cfg.acp.adapter)) {
-        return `acp.adapter "${cfg.acp.adapter}" is not a known profile; set acp.command to override or use one of: claude, codex`;
+    else {
+        const lower = stateName.toLowerCase();
+        for (const name of Object.keys(states)) {
+            if (name.toLowerCase() === lower) {
+                key = name;
+                break;
+            }
+        }
+    }
+    if (key === null)
+        return undefined;
+    return states[key].actions;
+}
+// Dispatch preflight validation (structural, pure). The fs-touching probes —
+// `tracker.root` existence and the adapter credential files — live in the shell
+// loader's `validateDispatchIo`, which the orchestrator calls alongside this
+// function. Both adapters are startup-probed: claude requires a single readable
+// host file (`~/.claude/.credentials.json`); codex passes when either
+// `~/.codex/auth.json` holds a token (ChatGPT-OAuth `tokens.access_token` or a
+// top-level `OPENAI_API_KEY`) or the host `OPENAI_API_KEY` env var is set. Keeping this
+// structural half pure means tests and the reload tick can re-run it cheaply on
+// every reconcile without re-hitting the disk.
+export function validateDispatch(cfg) {
+    if (cfg.tracker.kind !== 'local') {
+        return `unsupported_tracker_kind: ${cfg.tracker.kind || '<missing>'}`;
     }
+    if (!cfg.tracker.root)
+        return 'tracker.root must be set for local tracker';
+    // `cfg.states` is always populated by buildServiceConfig — the parser refuses
+    // workflows without a `states:` block — so callers never need a fallback here.
+    const statesError = validateStates(cfg.states);
+    if (statesError)
+        return statesError;
+    // cfg.agent is always populated by buildServiceConfig; guard for legacy
+    // hand-built ServiceConfigs (older test fixtures) that omit the block.
+    const concurrencyError = validateConcurrencyCaps(cfg.states, cfg.agent?.max_concurrent_agents);
+    if (concurrencyError)
+        return concurrencyError;
+    if (!isKnownAdapter(cfg.acp.adapter)) {
+        return `acp.adapter "${cfg.acp.adapter}" is not a known profile; use one of: claude, codex, opencode`;
+    }
+    // PR autopilot routing (issue 139) is validated structurally inside
+    // `validateStates` (pr: only on terminal states; on_conflict.route_to must be
+    // a declared state; at most one merge/close state). The state's own `role` is
+    // authoritative, so the old `validatePrAutopilot` role re-validator is gone.
+    // Auto-arm trigger (issue 140) is validated structurally inside
+    // `validateStates` (arm: only on active states; arm.from must be a declared
+    // holding state; arm.issue required; at most one armed state). The state's own
+    // `role` is authoritative, so the old `validateSleepCycle` role re-validator is
+    // gone.
     return null;
 }
-// Build + watch a workflow source. Throws on initial load failure.
-export async function watchWorkflow(workflowPath) {
-    const workflowAbs = path.resolve(workflowPath);
-    const initialDef = await loadWorkflow(workflowAbs);
-    const initialCfg = buildServiceConfig(initialDef.config, workflowAbs);
-    let current = { definition: initialDef, config: initialCfg };
-    const listeners = new Set();
-    const watcher = chokidar.watch(workflowAbs, {
-        ignoreInitial: true,
-        persistent: true,
-    });
-    let reloadInFlight = null;
-    const reload = async () => {
-        if (reloadInFlight)
-            return reloadInFlight;
-        reloadInFlight = (async () => {
-            try {
-                const def = await loadWorkflow(workflowAbs);
-                const cfg = buildServiceConfig(def.config, workflowAbs);
-                current = { definition: def, config: cfg };
-                log.info('workflow reloaded', { path: workflowAbs });
-                for (const cb of listeners)
-                    cb({ definition: def, config: cfg });
+/**
+ * Validate that the sum of per-state `max_concurrent` caps does not exceed the
+ * global `agent.max_concurrent_agents` host ceiling (issue 137). A sum greater
+ * than the ceiling can never be satisfied — the global clamp binds first — so it
+ * is almost always a misconfiguration worth surfacing at startup. Returns null
+ * when in budget or when the ceiling is unknown (legacy hand-built configs that
+ * omit `agent`). The legacy by-name map is already folded into the per-state
+ * caps by the time this runs, so its entries count toward the sum too.
+ */
+function validateConcurrencyCaps(states, ceiling) {
+    if (typeof ceiling !== 'number')
+        return null;
+    let sum = 0;
+    for (const sc of Object.values(states)) {
+        if (typeof sc.max_concurrent === 'number')
+            sum += sc.max_concurrent;
+    }
+    if (sum > ceiling) {
+        return `sum of per-state max_concurrent caps (${sum}) exceeds agent.max_concurrent_agents (${ceiling})`;
+    }
+    return null;
+}
+// State-map validation, exposed as a string|null so it composes with the rest of
+// `validateDispatch`. Checks declared in the same order the operator would hit
+// them while iterating on a malformed workflow: structural (roles, uniqueness),
+// then cross-references (allowed_transitions targets), then host-resource
+// dependencies (adapter known + credential readable).
+function validateStates(states) {
+    const names = Object.keys(states);
+    if (names.length === 0)
+        return 'states: at least one state must be declared';
+    let hasActive = false;
+    let hasTerminal = false;
+    let hasHolding = false;
+    for (const cfg of Object.values(states)) {
+        if (cfg.role === 'active')
+            hasActive = true;
+        else if (cfg.role === 'terminal')
+            hasTerminal = true;
+        else if (cfg.role === 'holding')
+            hasHolding = true;
+    }
+    if (!hasActive)
+        return 'states: at least one state must have role: active';
+    if (!hasTerminal)
+        return 'states: at least one state must have role: terminal';
+    // `holding` is required so `propose_issue` always has a declared landing
+    // directory; the dashboard's triage approve/discard surface also needs it.
+    if (!hasHolding)
+        return 'states: at least one state must have role: holding';
+    const seen = new Map();
+    for (const name of names) {
+        const key = name.toLowerCase();
+        const prior = seen.get(key);
+        if (prior !== undefined) {
+            return `states: duplicate state name (case-insensitive): "${prior}" and "${name}"`;
+        }
+        seen.set(key, name);
+    }
+    // PR autopilot routing (issue 139): `pr:` is only meaningful on a terminal
+    // state, `on_conflict.route_to` must name a declared state, and at most one
+    // terminal state may declare the merge (`auto_merge`) or close (`close`)
+    // behavior so `derivePrRouting`'s first-match is unambiguous.
+    let mergeStateCount = 0;
+    let closeStateCount = 0;
+    let armStateCount = 0;
+    for (const [name, cfg] of Object.entries(states)) {
+        if (cfg.allowed_transitions) {
+            for (const target of cfg.allowed_transitions) {
+                if (!seen.has(target.toLowerCase())) {
+                    return `state "${name}": allowed_transitions references undeclared state "${target}"`;
+                }
             }
-            catch (err) {
-                const e = err instanceof WorkflowError
-                    ? err
-                    : new WorkflowError('workflow_parse_error', err.message);
-                log.warn('workflow reload failed; keeping last good config', { error: e.message, code: e.code });
-                for (const cb of listeners)
-                    cb({ error: e });
+        }
+        if (cfg.adapter !== undefined && !isKnownAdapter(cfg.adapter)) {
+            return `state "${name}": adapter "${cfg.adapter}" is not a known profile; use one of: claude, codex, opencode`;
+        }
+        if (cfg.pr) {
+            if (cfg.role !== 'terminal') {
+                return `state "${name}": pr: is only valid on a terminal state (got role: ${cfg.role})`;
             }
-            finally {
-                reloadInFlight = null;
+            if (cfg.pr.auto_merge)
+                mergeStateCount += 1;
+            if (cfg.pr.close)
+                closeStateCount += 1;
+            const routeTo = cfg.pr.on_conflict?.route_to;
+            if (routeTo && !seen.has(routeTo.toLowerCase())) {
+                return `state "${name}": pr.on_conflict.route_to references undeclared state "${routeTo}"`;
             }
-        })();
-        return reloadInFlight;
-    };
-    watcher.on('change', () => void reload());
-    watcher.on('add', () => void reload());
-    // §5.5: workflow read errors must block dispatch. If the file is deleted or temporarily
-    // renamed, surface a missing_workflow_file error so the orchestrator knows.
-    watcher.on('unlink', () => void reload());
-    return {
-        current: () => current,
-        onChange: (cb) => {
-            listeners.add(cb);
-            return () => listeners.delete(cb);
-        },
-        stop: () => watcher.close(),
-    };
+        }
+        // Auto-arm trigger (issue 140): `arm:` is only meaningful on an active state,
+        // `arm.issue` is required, `arm.from` must name a declared holding state, and
+        // at most one active state may declare arm so `deriveArmRouting`'s first-match
+        // is unambiguous. The state's own `role` is authoritative — no separate
+        // sleep-cycle role re-validator.
+        if (cfg.arm) {
+            armStateCount += 1;
+            if (cfg.role !== 'active') {
+                return `state "${name}": arm: is only valid on an active state (got role: ${cfg.role})`;
+            }
+            if (!cfg.arm.issue || cfg.arm.issue.trim().length === 0) {
+                return `state "${name}": arm.issue is required (the recurring issue to arm into this state)`;
+            }
+            const fromCanonical = seen.get(cfg.arm.from.toLowerCase());
+            if (!fromCanonical) {
+                return `state "${name}": arm.from references undeclared state "${cfg.arm.from}"`;
+            }
+            if (states[fromCanonical].role !== 'holding') {
+                return `state "${name}": arm.from "${cfg.arm.from}" must be a holding state (got role: ${states[fromCanonical].role})`;
+            }
+        }
+    }
+    if (armStateCount > 1) {
+        return `states: at most one active state may declare arm (found ${armStateCount})`;
+    }
+    if (mergeStateCount > 1) {
+        return `states: at most one terminal state may declare pr.auto_merge (found ${mergeStateCount})`;
+    }
+    if (closeStateCount > 1) {
+        return `states: at most one terminal state may declare pr.close (found ${closeStateCount})`;
+    }
+    return null;
 }
 //# sourceMappingURL=workflow.js.map