@archmax-ai/harness 0.0.0

package/dist/machine/delegation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The delegation bounds a dispatcher enforces by default. Declared apart from the
+ * dispatcher so a host configuring `bounds` — or a browser-side editor showing
+ * what a workflow overrides — reads them without the LangGraph runtime.
+ */
+/** Default nesting bound: a sub-workflow session is a whole extra agent session. */
+export declare const DEFAULT_SUB_WORKFLOW_DEPTH = 3;
+/** Default fan-out bound for one session's in-flight sub-workflow sessions. */
+export declare const DEFAULT_SUB_WORKFLOW_CONCURRENCY = 4;

package/dist/machine/delegation.js

@@ -0,0 +1,10 @@
+/**
+ * The delegation bounds a dispatcher enforces by default. Declared apart from the
+ * dispatcher so a host configuring `bounds` — or a browser-side editor showing
+ * what a workflow overrides — reads them without the LangGraph runtime.
+ */
+/** Default nesting bound: a sub-workflow session is a whole extra agent session. */
+export const DEFAULT_SUB_WORKFLOW_DEPTH = 3;
+/** Default fan-out bound for one session's in-flight sub-workflow sessions. */
+export const DEFAULT_SUB_WORKFLOW_CONCURRENCY = 4;
+//# sourceMappingURL=delegation.js.map

package/dist/machine/delegation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.js","sourceRoot":"","sources":["../../src/machine/delegation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC"}

package/dist/machine/diagnostic.d.ts

@@ -0,0 +1,14 @@
+/** Severity of a finding about an authored workspace. */
+export type DiagnosticSeverity = "error" | "warning";
+/**
+ * One finding about a workflow, produced by the spec lint and by
+ * `validateWorkflow`, identifying the offending file and/or spec field.
+ */
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    /** Workspace-relative file the finding relates to, when applicable. */
+    file?: string;
+    /** Dotted spec field the finding relates to (`states.review.transitions.0.to`). */
+    field?: string;
+}

package/dist/machine/diagnostic.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=diagnostic.js.map

package/dist/machine/diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.js","sourceRoot":"","sources":["../../src/machine/diagnostic.ts"],"names":[],"mappings":""}

package/dist/machine/lint-spec.d.ts

@@ -0,0 +1,4 @@
+import type { Diagnostic } from "./diagnostic.js";
+import type { MachineSpec } from "./types.js";
+/** Findings for a spec the schema has accepted. `file` is left to the caller. */
+export declare function lintSpec(spec: MachineSpec): Diagnostic[];

package/dist/machine/lint-spec.js

@@ -0,0 +1,266 @@
+/**
+ * Findings about one `workflow.yaml` that do not stop it loading: warnings about
+ * things that run but almost certainly do not do what the author meant, and
+ * **errors** the runtime tolerates but `archmax validate` fails on (a human state
+ * that cannot present the decision it declares). Pure over the parsed spec — no
+ * workspace, no registry — so the loader and the validator report the same
+ * findings. What the runtime cannot run without lives in `spec-schema.ts`.
+ */
+import { classifyWorkspacePath, SESSION_OPEN_DIR } from "../core/zones.js";
+import { guardReferences, normalizeAllowEntry } from "./allow.js";
+import { normalizeMountGrants } from "./mount-grants.js";
+import { triggerDeclarationSchema } from "./spec-schema.js";
+import { ADVANCE_TOOL, ESSENTIAL_TOOLS } from "./tool-names.js";
+import { declaredVariableNames } from "./triggers.js";
+import { TRIGGER_VARIABLE } from "./variables.js";
+/** The block keys the SDK defines; anything else on a declaration is the host's. */
+const TRIGGER_KEYS = new Set(Object.keys(triggerDeclarationSchema.shape));
+const LABELED_TRANSITION_TYPES = ["approve", "reject", "refine"];
+/** Findings for a spec the schema has accepted. `file` is left to the caller. */
+export function lintSpec(spec) {
+    const out = [];
+    const warn = (field, message) => out.push({ severity: "warning", message, field });
+    const error = (field, message) => out.push({ severity: "error", message, field });
+    if (spec.instructions === undefined) {
+        warn("instructions", `No top-level 'instructions', so the workflow ships no standing guidance in the system ` +
+            `prompt — conventions, house rules, and what "done" means have to be repeated in every ` +
+            `state's 'instructions' instead. Add an 'instructions' block for direction that holds ` +
+            `across the whole run.`);
+    }
+    // Validation is the one surface that stays fully functional for a disabled
+    // workflow, so it has to say plainly that runs will be refused.
+    if (spec.disabled === true) {
+        warn("disabled", `This workflow is disabled ('disabled: true'), so it starts no new turns: 'archmax run' ` +
+            `refuses, a trigger firing is rejected, and a caller's delegation call is refused. ` +
+            `Sessions already underway can still be decided, replied to and delivered to, and ` +
+            `'archmax test' skips its cases. Remove the key to re-enable it.`);
+    }
+    // Essential built-ins are always permitted, and only a state's own entry
+    // narrows them — so an `allow_always` entry naming one is inert. `task` is
+    // conditional, so an entry naming it can be what discloses it.
+    for (const entry of spec.tools?.allow_always ?? []) {
+        const { tool, argMatchers } = normalizeAllowEntry(entry);
+        if (!tool || !ESSENTIAL_TOOLS.has(tool))
+            continue;
+        warn("tools.allow_always", argMatchers
+            ? `'tools.allow_always' constrains essential tool '${tool}', but essential tools are always permitted and the constraint is never enforced; narrow it per state with a 'tools.allow' entry instead`
+            : `'tools.allow_always' lists essential tool '${tool}', which is always permitted; the entry is redundant`);
+    }
+    const alwaysSkills = spec.skills?.allow_always;
+    const forbiddenSkills = spec.skills?.forbid_always ?? [];
+    // A workflow-wide skill denial beats every grant, so a grant it covers reaches
+    // no state at all.
+    for (const named of forbiddenSkills) {
+        const grantedSomewhere = (alwaysSkills ?? []).includes(named) ||
+            Object.values(spec.states).some((state) => (state.skills?.allow ?? []).includes(named));
+        if (!grantedSomewhere)
+            continue;
+        warn("skills.forbid_always", `'skills.forbid_always' denies skill '${named}' in every state while a 'skills.allow' or ` +
+            `'skills.allow_always' list also grants it; a denial beats every grant, so the grant ` +
+            `reaches nothing. Drop one of the two.`);
+    }
+    const alwaysMounts = normalizeMountGrants(spec.mounts?.allow_always);
+    const alwaysMountNames = alwaysMounts.map((grant) => grant.mount);
+    const forbiddenMounts = spec.mounts?.forbid_always ?? [];
+    // A workflow-wide mount denial beats every grant, so a grant it covers reaches
+    // no state at all — the mounts twin of the skills lint above.
+    for (const named of forbiddenMounts) {
+        const grantedSomewhere = alwaysMountNames.includes(named) ||
+            Object.values(spec.states).some((state) => normalizeMountGrants(state.mounts?.allow).some((grant) => grant.mount === named));
+        if (!grantedSomewhere)
+            continue;
+        warn("mounts.forbid_always", `'mounts.forbid_always' denies mount '${named}' in every state while a 'mounts.allow' or ` +
+            `'mounts.allow_always' list also grants it; a denial beats every grant, so the grant ` +
+            `reaches nothing. Drop one of the two.`);
+    }
+    // The workflow-wide tool denial that strands every run: no state could leave
+    // itself, so nothing reaches a terminal state.
+    const hasNonTerminal = Object.values(spec.states).some((state) => (state.transitions ?? []).length > 0);
+    for (const entry of spec.tools?.forbid_always ?? []) {
+        const { tool } = normalizeAllowEntry(entry);
+        if (tool !== ADVANCE_TOOL || !hasNonTerminal)
+            continue;
+        error("tools.forbid_always", `'tools.forbid_always' denies '${ADVANCE_TOOL}', the only way a state moves, in a workflow ` +
+            `that has outgoing transitions — so no run could ever leave its start state. Deny a tool ` +
+            `the graph does not need, or remove the entry.`);
+    }
+    for (const [slug, state] of Object.entries(spec.states)) {
+        const at = `states.${slug}`;
+        const transitions = state.transitions ?? [];
+        // A state's model overrides the workflow's; naming the same id overrides it
+        // with itself, which reads as a deliberate choice while changing nothing.
+        if (state.model !== undefined && state.model === spec.settings?.model) {
+            warn(`${at}.model`, `State '${slug}' declares model '${state.model}', which is already ` +
+                `'settings.model' for the whole workflow; the entry changes nothing. Drop it, or name ` +
+                `a different id if this state should run on another model.`);
+        }
+        // A state's list adds; only its `forbid` takes away, so an entry the workflow
+        // already grants everywhere governs nothing, and an empty list that reads
+        // like a deny is not one.
+        if (alwaysSkills !== undefined && alwaysSkills.length > 0) {
+            const declaredSkills = state.skills?.allow;
+            if (declaredSkills !== undefined && declaredSkills.length === 0) {
+                warn(`${at}.skills.allow`, `State '${slug}' declares 'skills: { allow: [] }', which reads like a deny but subtracts ` +
+                    `nothing: 'skills.allow_always' enables ${alwaysSkills.join(", ")} in every state. ` +
+                    `'skills: { forbid: [...] }' is what subtracts — name the slugs this state must not ` +
+                    `have there.`);
+            }
+            for (const named of declaredSkills ?? []) {
+                if (!alwaysSkills.includes(named))
+                    continue;
+                warn(`${at}.skills.allow`, `State '${slug}' enables skill '${named}', which 'skills.allow_always' already enables ` +
+                    `in every state; the entry grants nothing. Drop it here, or drop it from ` +
+                    `'allow_always' if only some states should have it.`);
+            }
+        }
+        // The same three shapes for mounts. `access` is why the both-levels case is
+        // not simply redundant: a state entry that narrows the workflow's grant to
+        // reads is doing real work, so only one repeating it unchanged is warned.
+        const stateMounts = normalizeMountGrants(state.mounts?.allow);
+        if (alwaysMountNames.length > 0) {
+            if (Array.isArray(state.mounts?.allow) && stateMounts.length === 0) {
+                warn(`${at}.mounts.allow`, `State '${slug}' declares 'mounts: { allow: [] }', which reads like a deny but ` +
+                    `subtracts nothing: 'mounts.allow_always' enables ${alwaysMountNames.join(", ")} in ` +
+                    `every state. 'mounts: { forbid: [...] }' is what subtracts — name the mounts this ` +
+                    `state must not reach.`);
+            }
+            for (const grant of stateMounts) {
+                if (!alwaysMountNames.includes(grant.mount))
+                    continue;
+                const narrows = grant.access === "read" &&
+                    alwaysMounts.some((a) => a.mount === grant.mount && a.access !== "read");
+                if (narrows)
+                    continue;
+                warn(`${at}.mounts.allow`, `State '${slug}' enables mount '${grant.mount}', which 'mounts.allow_always' already ` +
+                    `enables in every state; the entry grants nothing. Write ` +
+                    `'{ mount: ${grant.mount}, access: read }' if the intent is to narrow it here, ` +
+                    `'mounts.forbid' to take it away, or drop it from 'allow_always' if only some ` +
+                    `states should have it.`);
+            }
+        }
+        for (const named of state.mounts?.forbid ?? []) {
+            if (stateMounts.some((grant) => grant.mount === named)) {
+                warn(`${at}.mounts.allow`, `State '${slug}' both enables and forbids mount '${named}'; the denial wins, so the ` +
+                    `'allow' entry governs nothing. Drop one of the two.`);
+            }
+        }
+        // A state's own denial beats its own grant, so a slug or tool it both grants
+        // and denies is a grant that governs nothing.
+        const stateForbidSkills = state.skills?.forbid ?? [];
+        for (const named of stateForbidSkills) {
+            if ((state.skills?.allow ?? []).includes(named)) {
+                warn(`${at}.skills.allow`, `State '${slug}' both enables and forbids skill '${named}'; the denial wins, so the ` +
+                    `'allow' entry governs nothing. Drop one of the two.`);
+                continue;
+            }
+            // Nothing granted it here, so the denial has nothing to subtract.
+            if (!(alwaysSkills ?? []).includes(named) && !forbiddenSkills.includes(named)) {
+                warn(`${at}.skills.forbid`, `State '${slug}' forbids skill '${named}', which nothing enables here — neither ` +
+                    `'skills.allow_always' nor this state's own 'skills.allow' names it — so the entry ` +
+                    `governs nothing.`);
+            }
+        }
+        const stateAllowTools = new Set((state.tools?.allow ?? []).map((entry) => normalizeAllowEntry(entry).tool));
+        for (const entry of state.tools?.forbid ?? []) {
+            const { tool } = normalizeAllowEntry(entry);
+            if (!tool || !stateAllowTools.has(tool))
+                continue;
+            warn(`${at}.tools.allow`, `State '${slug}' both allows and forbids '${tool}'; the denial wins, so the 'allow' entry ` +
+                `governs nothing. Drop one of the two.`);
+        }
+        // A state with several outgoing edges is making a routing decision, which
+        // belongs to its own `instructions`. Human states require them already.
+        if (state.type !== "human" && transitions.length > 1 && !state.instructions?.trim()) {
+            warn(`${at}.instructions`, `State '${slug}' has ${transitions.length} outgoing transitions but no 'instructions'; add guidance so the agent classifies the request and routes with archmax_advance instead of leaving that decision to whichever state it lands in`);
+        }
+        // No routing-context advisory here: every transition now carries a non-empty
+        // `description` by schema, and a state's `summary` reaches no model call.
+        if (state.type === "human") {
+            if (!state.instructions?.trim()) {
+                error(`${at}.instructions`, `Human state '${slug}' must declare 'instructions' describing the decision to present`);
+            }
+            if (transitions.length === 0) {
+                error(`${at}.transitions`, `Human state '${slug}' must declare at least one outgoing transition the human can route to`);
+            }
+            // A missing button label is not checked here: the schema requires a
+            // non-empty `description` on every transition, human or not.
+            transitions.forEach((transition, index) => {
+                // A decision routes the run *out* of the state: a self-edge is offered as
+                // a button and then ends the run instead of routing.
+                if (transition.to === slug) {
+                    error(`${at}.transitions.${index}.to`, `Human state '${slug}' declares a transition to itself; a decision routes the run ` +
+                        `*out* of the state, so this edge would be offered to the reviewer and then end ` +
+                        `the run. Point it at the state that does the further work (e.g. the state that ` +
+                        `produced what is being reviewed)`);
+                }
+            });
+            for (const labeled of LABELED_TRANSITION_TYPES) {
+                const count = transitions.filter((transition) => transition.type === labeled).length;
+                if (count > 1) {
+                    error(`${at}.transitions`, `Human state '${slug}' declares ${count} '${labeled}' transitions; a labeled ` +
+                        `decision type must map to a single target`);
+                }
+            }
+            // Every hook site lives inside an agent turn, and a human state runs
+            // none: a hook here validates cleanly and is never called.
+            for (const phase of ["before", "after"]) {
+                if (state[phase] === undefined)
+                    continue;
+                error(`${at}.${phase}`, `Human state '${slug}' declares a '${phase}' hook, which can never run: hooks execute ` +
+                    `inside an agent segment and a human state runs none — it presents the decision and ` +
+                    `waits for a person. Move it to the agent state ` +
+                    `${phase === "before" ? "that advances into" : "the decision routes to"} this state`);
+            }
+        }
+        const seen = new Set();
+        for (const name of state.requires ?? []) {
+            if (seen.has(name))
+                warn(`${at}.requires`, `State '${slug}' lists '${name}' twice in requires.`);
+            seen.add(name);
+        }
+        // An entry whose every path sits in the always-open working area reads as
+        // governance but cannot act as one there: `tool.scratchpad` allows the write
+        // before the state's list is consulted, in every state.
+        for (const entry of state.tools?.allow ?? []) {
+            const { tool, argMatchers } = normalizeAllowEntry(entry);
+            if ((tool !== "write_file" && tool !== "edit_file") || !argMatchers)
+                continue;
+            const paths = argMatchers.file_path ?? [];
+            if (paths.length === 0 || !paths.every((path) => classifyWorkspacePath(path) === "run-open")) {
+                continue;
+            }
+            warn(`${at}.tools.allow`, `State '${slug}' allows '${tool}' on ${paths.map((p) => `'${p}'`).join(", ")}, which is in the always-open '${SESSION_OPEN_DIR}/' area: those writes are permitted in every state regardless of this entry, so it does not constrain where inside '${SESSION_OPEN_DIR}/' the write may land. Name an ordinary run path (e.g. '${slug}.json') if the write itself should be governed.`);
+        }
+    }
+    // A declaration is loose, so a host may decorate it; the SDK reads the keys it
+    // knows and says so about the rest. There is nothing left to warn about an
+    // orphaned declaration: writing one is what makes its state a start state.
+    for (const [slug, state] of Object.entries(spec.states)) {
+        for (const [id, decl] of Object.entries(state.triggers ?? {})) {
+            for (const key of Object.keys(decl ?? {})) {
+                if (TRIGGER_KEYS.has(key))
+                    continue;
+                warn(`states.${slug}.triggers.${id}`, `Trigger '${id}' declares unknown key '${key}', which the SDK ignores. The keys it reads are ${[...TRIGGER_KEYS].map((k) => `'${k}'`).join(", ")}.`);
+            }
+        }
+    }
+    // A guard on a variable nothing declares rests on the agent having called
+    // set_variables first. Not an error: the host may seed it at assembly, where
+    // the authoritative check runs with the seeds known.
+    const declared = declaredVariableNames(spec);
+    for (const ref of guardReferences(spec)) {
+        const name = ref.reference.name;
+        if (name === TRIGGER_VARIABLE || declared.has(name))
+            continue;
+        const where = ref.state ? `State '${ref.state}'` : "tools.allow_always";
+        warn(ref.state ? `states.${ref.state}.tools.allow` : "tools.allow_always", `${where} guards '${ref.tool ?? "?"}' on '${ref.reference.raw}', but no state requires ` +
+            `'${name}'. Supply it through the 'variables' option at assembly, or name it in the ` +
+            `'requires' of a state that runs first — otherwise the guard depends on the agent ` +
+            `having called set_variables, and the run fails at that call if it has not.` +
+            (ref.state
+                ? ""
+                : " An allow_always entry is evaluated in every state, including states reached before anything sets it."));
+    }
+    return out;
+}
+//# sourceMappingURL=lint-spec.js.map

package/dist/machine/lint-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-spec.js","sourceRoot":"","sources":["../../src/machine/lint-spec.ts"],"names":[],"mappings":"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"}

package/dist/machine/load-spec.d.ts

@@ -0,0 +1,90 @@
+import type { Workspace } from "../core/workspace.js";
+import type { MachineSpec } from "./types.js";
+/**
+ * The distinct ways loading a machine spec can fall short of a usable machine.
+ * Each consumer maps these to its own reporting surface (runtime warning events
+ * vs. static validator diagnostics), so both agree on *why* a spec is unusable.
+ */
+export type LoadIssueKind = "missing" | "not-a-mapping" | "schema" | "competing-machines" | "lint";
+export interface LoadIssue {
+    kind: LoadIssueKind;
+    /**
+     * `error` issues make the spec unusable (fail-closed), except `lint` errors,
+     * which the runtime tolerates and `validate` fails on; `warning` issues are
+     * surfaced but the machine still loads.
+     */
+    severity: "error" | "warning";
+    /** Self-describing message, naming the file, for the runtime's warning events. */
+    message: string;
+    /** Dotted spec field the issue relates to, when the schema or lint named one. */
+    field?: string;
+}
+export interface LoadSpecResult {
+    /**
+     * The parsed machine spec when a spec file exists and parses to a mapping —
+     * even if it later fails the schema, so the static validator can keep
+     * inspecting it. `null` only when there is nothing parseable to inspect.
+     */
+    spec: MachineSpec | null;
+    /** Structured problems found while loading; empty when the spec is pristine. */
+    issues: LoadIssue[];
+    /**
+     * Advisory findings from `lintSpec` (kind `lint`): never load-blocking; the
+     * runtime emits them as warnings and `archmax validate` reports them (an
+     * error-severity lint finding fails validation, not the load).
+     */
+    lint: LoadIssue[];
+    /** Prose addendum: the sibling `WORKFLOW.md` content (empty when absent). */
+    body: string;
+    /** Workspace-relative path the machine spec was loaded from (for diagnostics). */
+    specFile: string;
+    /**
+     * Whether the loaded spec is a usable machine: it passed the schema and has
+     * no error-severity issues. The runtime builds a `WorkflowMachine` only when
+     * this is true.
+     */
+    usable: boolean;
+}
+/** The two files a workflow is authored in. */
+export interface WorkflowSpecPaths {
+    /** The machine spec: `workflows/<slug>/workflow.yaml`. */
+    workflowYaml: string;
+    /** Optional prose addendum: `workflows/<slug>/WORKFLOW.md` (never a spec source). */
+    workflow: string;
+}
+/**
+ * Single implementation of machine-spec loading, shared by runtime assembly and
+ * the static validator. `workflow.yaml` is the sole spec source: a sibling
+ * `WORKFLOW.md` is prose only, and frontmatter there is a `competing-machines`
+ * error. Shape, document rules and advisories come from `validateSpec`.
+ */
+export declare function loadMachineSpec(workspace: Workspace, paths: WorkflowSpecPaths): Promise<LoadSpecResult>;
+/**
+ * Thrown by `createAgent` when a requested workflow cannot be loaded: its
+ * `workflow.yaml` is missing, or exists but has no valid machine spec. Assembly
+ * fails closed rather than silently degrading to an ungoverned plain agent.
+ */
+export declare class WorkflowLoadError extends Error {
+    /** Workflow slug the load was attempted for. */
+    readonly workflow: string;
+    /** Workspace-relative path of the workflow definition. */
+    readonly workflowPath: string;
+    /** What went wrong (missing file vs invalid machine spec). */
+    readonly problem: string;
+    constructor(
+    /** Workflow slug the load was attempted for. */
+    workflow: string, 
+    /** Workspace-relative path of the workflow definition. */
+    workflowPath: string, 
+    /** What went wrong (missing file vs invalid machine spec). */
+    problem: string);
+}
+/**
+ * Thrown when a turn would start a session on a workflow that declares
+ * `disabled: true`. Parked sessions can still be decided, replied to and
+ * delivered to; only a new turn is refused.
+ */
+export declare class WorkflowDisabledError extends Error {
+    readonly workflow: string;
+    constructor(workflow: string);
+}

package/dist/machine/load-spec.js

@@ -0,0 +1,120 @@
+import { parse as parseYaml } from "yaml";
+import { parseFrontmatter } from "../core/frontmatter.js";
+import { validateSpec } from "./validate-spec.js";
+/**
+ * Single implementation of machine-spec loading, shared by runtime assembly and
+ * the static validator. `workflow.yaml` is the sole spec source: a sibling
+ * `WORKFLOW.md` is prose only, and frontmatter there is a `competing-machines`
+ * error. Shape, document rules and advisories come from `validateSpec`.
+ */
+export async function loadMachineSpec(workspace, paths) {
+    const specFile = paths.workflowYaml;
+    const yamlRaw = await workspace.readText(specFile);
+    if (yamlRaw == null) {
+        return {
+            spec: null,
+            issues: [{ kind: "missing", severity: "error", message: `${specFile} not found` }],
+            body: "",
+            specFile,
+            usable: false,
+            lint: [],
+        };
+    }
+    const issues = [];
+    let data;
+    try {
+        data = parseYaml(yamlRaw.replace(/\r(?=\n|$)/g, "")) ?? null;
+    }
+    catch {
+        data = null;
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        issues.push({
+            kind: "not-a-mapping",
+            severity: "error",
+            message: `invalid machine spec at ${specFile} (expected a YAML mapping)`,
+        });
+        return { spec: null, issues, lint: [], body: "", specFile, usable: false };
+    }
+    // One validator for the loader and the editor-facing `validateSpec`: the
+    // shape and document rules here are exactly what it reports.
+    const checked = validateSpec(data);
+    for (const finding of checked.schema) {
+        issues.push({
+            kind: "schema",
+            severity: "error",
+            message: `${specFile}: ${finding.field ? `'${finding.field}': ` : ""}${finding.message}`,
+            ...(finding.field ? { field: finding.field } : {}),
+        });
+    }
+    // The lint reads typed fields, so it runs whenever the shape held — including
+    // beside a document-level error, so one dangling target does not hide every
+    // advisory behind it.
+    const lint = checked.lint.map((finding) => ({
+        kind: "lint",
+        severity: finding.severity,
+        message: `${specFile}: ${finding.message}`,
+        ...(finding.field ? { field: finding.field } : {}),
+    }));
+    // The unvalidated mapping is carried forward when the schema rejects it, so the
+    // validator's cross-file passes still run; `usable` is false, so nothing runs it.
+    const spec = checked.ok && checked.spec ? checked.spec : data;
+    let body = "";
+    const proseRaw = await workspace.readText(paths.workflow);
+    if (proseRaw != null) {
+        if (parseFrontmatter(proseRaw)) {
+            issues.push({
+                kind: "competing-machines",
+                severity: "error",
+                message: `${paths.workflow} declares YAML frontmatter but ${specFile} is the ` +
+                    `machine spec; remove the frontmatter from ${paths.workflow} (it is prose only).`,
+            });
+        }
+        body = proseRaw;
+    }
+    // A lint error fails `validate`, not the load: the runtime tolerates what it
+    // reports, so a run is not refused over a missing button label. Lint lives in
+    // its own list so `issues` keeps meaning "what stands between this file and a
+    // usable machine" — a host asserting `issues` is empty for a valid spec is right.
+    const usable = !issues.some((i) => i.severity === "error");
+    return { spec, issues, lint, body, specFile, usable };
+}
+/**
+ * Thrown by `createAgent` when a requested workflow cannot be loaded: its
+ * `workflow.yaml` is missing, or exists but has no valid machine spec. Assembly
+ * fails closed rather than silently degrading to an ungoverned plain agent.
+ */
+export class WorkflowLoadError extends Error {
+    workflow;
+    workflowPath;
+    problem;
+    constructor(
+    /** Workflow slug the load was attempted for. */
+    workflow, 
+    /** Workspace-relative path of the workflow definition. */
+    workflowPath, 
+    /** What went wrong (missing file vs invalid machine spec). */
+    problem) {
+        super(`Cannot load workflow '${workflow}' (${workflowPath}): ${problem}. ` +
+            `Run 'archmax validate ${workflow}' for details.`);
+        this.workflow = workflow;
+        this.workflowPath = workflowPath;
+        this.problem = problem;
+        this.name = "WorkflowLoadError";
+    }
+}
+/**
+ * Thrown when a turn would start a session on a workflow that declares
+ * `disabled: true`. Parked sessions can still be decided, replied to and
+ * delivered to; only a new turn is refused.
+ */
+export class WorkflowDisabledError extends Error {
+    workflow;
+    constructor(workflow) {
+        super(`workflow '${workflow}' is disabled ('disabled: true' in its workflow.yaml); no session started. ` +
+            `Remove that flag to re-enable it. Parked sessions can still be decided, replied to and delivered to.`);
+        this.workflow = workflow;
+        this.name = "WorkflowDisabledError";
+    }
+}
+//# sourceMappingURL=load-spec.js.map

package/dist/machine/load-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-spec.js","sourceRoot":"","sources":["../../src/machine/load-spec.ts"],"names":[],"mappings":"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"}