stageflow 0.42.0 → 0.44.0

package/dist/compaction/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared contracts for Stageflow's built-in compaction (docs/plans/compaction-strategy.md).
+ * Pure data types only: the layers (mask, pin, state, summary, guards) import from here.
+ */
+export type PinnedFactKind = "id" | "number" | "timestamp" | "url" | "path" | "error" | "other";
+/** A value copied verbatim out of a message so a summary cannot lose or reword it. */
+export type PinnedFact = {
+    kind: PinnedFactKind;
+    /** The exact text, e.g. "INC-4471", "48211", "2026-03-14T05:52:03Z". */
+    value: string;
+    /** A short verbatim snippet around the value (single line, capped), for orientation. */
+    context: string;
+    /** Position in the message list the facts were extracted from, and the tool when from a tool result. */
+    source: {
+        messageIndex: number;
+        toolName?: string;
+    };
+};
+/** A tool result replaced by a placeholder in the model's context. */
+export type ClearedResult = {
+    toolName: string;
+    toolCallId: string;
+    /** Where the full output can be read again (a file path or a tool + args hint). */
+    recoverHint: string;
+    bytes: number;
+    /** One line describing what the result was, for the recovery index. */
+    descriptor: string;
+};
+export type WorkingStateKind = "fact" | "decision" | "progress" | "todo" | "blocker";
+/** One keyed entry in the model's working state (the `working_state` tool). */
+export type WorkingStateEntry = {
+    key: string;
+    kind: WorkingStateKind;
+    value: string;
+    updatedAt: string;
+};
+export declare const WORKING_STATE_TOOL_NAME = "working_state";
+/** Everything the compaction summary is built from, besides the model-written part. */
+export type CompactionSections = {
+    pinned: readonly PinnedFact[];
+    cleared: readonly ClearedResult[];
+    state: readonly WorkingStateEntry[];
+};
+/** Bumped whenever the focus prompt or section layout changes (like RUBRIC_PROMPT_VERSION). */
+export declare const COMPACTION_PROMPT_VERSION = 1;

package/dist/compaction/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared contracts for Stageflow's built-in compaction (docs/plans/compaction-strategy.md).
+ * Pure data types only: the layers (mask, pin, state, summary, guards) import from here.
+ */
+export const WORKING_STATE_TOOL_NAME = "working_state";
+/** Bumped whenever the focus prompt or section layout changes (like RUBRIC_PROMPT_VERSION). */
+export const COMPACTION_PROMPT_VERSION = 1;

package/dist/compaction/workingState.d.ts

@@ -0,0 +1,56 @@
+import type { WorkingStateEntry, WorkingStateKind } from "./types.js";
+export declare const WORKING_STATE_CUSTOM_TYPE = "stageflow.working_state";
+export declare const WORKING_STATE_KINDS: readonly WorkingStateKind[];
+export declare const WORKING_STATE_MAX_KEY = 80;
+export declare const WORKING_STATE_MAX_VALUE = 600;
+export declare const WORKING_STATE_MAX_ENTRIES = 60;
+export declare const WORKING_STATE_DEFAULT_RENDER_CHARS = 6000;
+export declare const WORKING_STATE_GUIDANCE = "Older messages and tool results are trimmed automatically as the conversation grows, so keep your own working state with the working_state tool. As soon as you learn or decide something you will need later, record it: exact values and identifiers (fact), choices and their reasons (decision), what is done (progress), what remains (todo) and what is stuck (blocker). Keep each entry to one or two short lines, update an existing key instead of adding a duplicate, and delete entries that no longer matter. Never store secrets or credentials in it.";
+export type WorkingStateEvent = {
+    op: "set";
+    key: string;
+    kind: WorkingStateKind;
+    value: string;
+    at: string;
+} | {
+    op: "delete";
+    key: string;
+    at: string;
+};
+export type WorkingStateSetResult = {
+    ok: true;
+    dropped: string[];
+    replaced: boolean;
+    redacted: boolean;
+    entry: WorkingStateEntry;
+} | {
+    ok: false;
+    error: string;
+};
+export type WorkingStateInput = {
+    key: string;
+    kind: WorkingStateKind;
+    value: string;
+    updatedAt?: string;
+};
+export declare class WorkingStateStore {
+    private readonly entries;
+    get size(): number;
+    set(input: WorkingStateInput): WorkingStateSetResult;
+    delete(key: string): boolean;
+    list(): WorkingStateEntry[];
+    apply(event: WorkingStateEvent): void;
+    load(events: readonly WorkingStateEvent[]): void;
+    render(maxChars?: number): string;
+    private oldestOfKind;
+}
+export declare function reduceWorkingState(events: readonly WorkingStateEvent[]): WorkingStateStore;
+type SessionEntryLike = {
+    type?: unknown;
+    customType?: unknown;
+    data?: unknown;
+};
+export declare function workingStateEventsFromEntries(entries: readonly SessionEntryLike[]): WorkingStateEvent[];
+export declare function restoreWorkingState(entries: readonly SessionEntryLike[]): WorkingStateStore;
+export declare function getWorkingStateSections(entries: readonly SessionEntryLike[]): WorkingStateEntry[];
+export {};

package/dist/compaction/workingState.js

@@ -0,0 +1,198 @@
+import { scrubSecrets } from "./scrub.js";
+export const WORKING_STATE_CUSTOM_TYPE = "stageflow.working_state";
+export const WORKING_STATE_KINDS = [
+    "fact",
+    "decision",
+    "progress",
+    "todo",
+    "blocker",
+];
+export const WORKING_STATE_MAX_KEY = 80;
+export const WORKING_STATE_MAX_VALUE = 600;
+export const WORKING_STATE_MAX_ENTRIES = 60;
+export const WORKING_STATE_DEFAULT_RENDER_CHARS = 6000;
+export const WORKING_STATE_GUIDANCE = "Older messages and tool results are trimmed automatically as the conversation grows, so keep your own working state with the working_state tool. As soon as you learn or decide something you will need later, record it: exact values and identifiers (fact), choices and their reasons (decision), what is done (progress), what remains (todo) and what is stuck (blocker). Keep each entry to one or two short lines, update an existing key instead of adding a duplicate, and delete entries that no longer matter. Never store secrets or credentials in it.";
+const RENDER_ORDER = [
+    "blocker",
+    "todo",
+    "decision",
+    "fact",
+    "progress",
+];
+const EVICTION_ORDER = [
+    "progress",
+    "fact",
+    "decision",
+    "todo",
+    "blocker",
+];
+const HEADINGS = {
+    blocker: "Blockers",
+    todo: "Todo",
+    decision: "Decisions",
+    fact: "Facts",
+    progress: "Progress",
+};
+function isKind(value) {
+    return (typeof value === "string" &&
+        WORKING_STATE_KINDS.includes(value));
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+export class WorkingStateStore {
+    entries = new Map();
+    get size() {
+        return this.entries.size;
+    }
+    set(input) {
+        if (!isKind(input.kind)) {
+            return {
+                ok: false,
+                error: `kind must be one of ${WORKING_STATE_KINDS.join(", ")}`,
+            };
+        }
+        const rawKey = oneLine(String(input.key ?? ""));
+        const rawValue = oneLine(String(input.value ?? ""));
+        const key = oneLine(scrubSecrets(rawKey));
+        const value = oneLine(scrubSecrets(rawValue));
+        const redacted = key !== rawKey || value !== rawValue;
+        if (key.length === 0)
+            return { ok: false, error: "key is required" };
+        if (key.length > WORKING_STATE_MAX_KEY) {
+            return {
+                ok: false,
+                error: `key is ${key.length} chars; max ${WORKING_STATE_MAX_KEY}`,
+            };
+        }
+        if (value.length === 0)
+            return { ok: false, error: "value is required" };
+        if (value.length > WORKING_STATE_MAX_VALUE) {
+            return {
+                ok: false,
+                error: `value is ${value.length} chars; max ${WORKING_STATE_MAX_VALUE}. Shorten it.`,
+            };
+        }
+        const replaced = this.entries.delete(key);
+        const dropped = [];
+        while (this.entries.size >= WORKING_STATE_MAX_ENTRIES) {
+            const victim = this.oldestOfKind("progress");
+            if (victim === undefined) {
+                return {
+                    ok: false,
+                    error: `working state is full (${WORKING_STATE_MAX_ENTRIES} entries, none are progress). Delete entries first.`,
+                };
+            }
+            this.entries.delete(victim);
+            dropped.push(victim);
+        }
+        const entry = {
+            key,
+            kind: input.kind,
+            value,
+            updatedAt: input.updatedAt ?? new Date().toISOString(),
+        };
+        this.entries.set(key, entry);
+        return { ok: true, dropped, replaced, redacted, entry };
+    }
+    delete(key) {
+        const raw = oneLine(String(key ?? ""));
+        return this.entries.delete(raw) || this.entries.delete(oneLine(scrubSecrets(raw)));
+    }
+    list() {
+        return [...this.entries.values()];
+    }
+    apply(event) {
+        if (event.op === "set") {
+            this.set({
+                key: event.key,
+                kind: event.kind,
+                value: event.value,
+                updatedAt: event.at,
+            });
+        }
+        else if (event.op === "delete") {
+            this.delete(event.key);
+        }
+    }
+    load(events) {
+        this.entries.clear();
+        for (const event of events)
+            this.apply(event);
+    }
+    render(maxChars = WORKING_STATE_DEFAULT_RENDER_CHARS) {
+        const all = this.list();
+        if (all.length === 0)
+            return "";
+        const keep = new Set(all);
+        let omitted = 0;
+        const build = () => {
+            const lines = ["## Working state"];
+            for (const kind of RENDER_ORDER) {
+                const group = all.filter((e) => keep.has(e) && e.kind === kind);
+                if (group.length === 0)
+                    continue;
+                lines.push("", `### ${HEADINGS[kind]}`);
+                for (const e of group)
+                    lines.push(`- ${e.key}: ${e.value}`);
+            }
+            if (omitted > 0) {
+                lines.push("", `(${omitted} older entries omitted for space)`);
+            }
+            return lines.join("\n");
+        };
+        let text = build();
+        for (const kind of EVICTION_ORDER) {
+            for (const e of all) {
+                if (text.length <= maxChars)
+                    return text;
+                if (e.kind !== kind)
+                    continue;
+                keep.delete(e);
+                omitted += 1;
+                text = build();
+            }
+        }
+        return text.length <= maxChars ? text : text.slice(0, Math.max(0, maxChars));
+    }
+    oldestOfKind(kind) {
+        for (const e of this.entries.values()) {
+            if (e.kind === kind)
+                return e.key;
+        }
+        return undefined;
+    }
+}
+export function reduceWorkingState(events) {
+    const store = new WorkingStateStore();
+    for (const event of events)
+        store.apply(event);
+    return store;
+}
+function isEvent(data) {
+    if (data === null || typeof data !== "object")
+        return false;
+    const d = data;
+    if (typeof d.key !== "string")
+        return false;
+    if (d.op === "delete")
+        return true;
+    return d.op === "set" && isKind(d.kind) && typeof d.value === "string";
+}
+export function workingStateEventsFromEntries(entries) {
+    const events = [];
+    for (const entry of entries) {
+        if (entry.type === "custom" &&
+            entry.customType === WORKING_STATE_CUSTOM_TYPE &&
+            isEvent(entry.data)) {
+            events.push(entry.data);
+        }
+    }
+    return events;
+}
+export function restoreWorkingState(entries) {
+    return reduceWorkingState(workingStateEventsFromEntries(entries));
+}
+export function getWorkingStateSections(entries) {
+    return restoreWorkingState(entries).list();
+}

package/dist/config/createPipeline.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { ensureCatalogScanRoot } from "./ensureCatalogScanRoot.js";
 import { invertPredecessorEdgesToRoute, invertRouteToPredecessorEdges, parsePipelineNeeds, toPipelineNeeds, } from "./pipelineNeeds.js";
 import { STAGE_ID_PATTERN } from "./createStage.js";
 import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
@@ -548,6 +549,7 @@ export async function createPipeline(projectRoot, input) {
             error: errorFinding?.message ?? "Pipeline validation failed",
         };
     }
+    await ensureCatalogScanRoot(projectRoot, path.relative(projectRoot, pipelineDirectory));
     const loadOutcome = await loadPipelineOutcome(relPath, { cwd: projectRoot });
     if (!loadOutcome.ok) {
         await unlink(filePath).catch(() => { });

package/dist/config/createTrigger.js

@@ -6,6 +6,7 @@ import { STAGE_ID_PATTERN } from "./createStage.js";
 import { getCatalogScanPaths } from "./browseCatalog.js";
 import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { githubMatchActionError } from "./githubTriggerAction.js";
 import { loadTriggerOutcome } from "./loadTrigger.js";
 import { collectPipelineIdsFromPaths, collectTaskIdsFromPaths } from "./validateCatalog.js";
 import { findCatalogPathById } from "../runtime/triggerCatalog.js";
@@ -56,11 +57,16 @@ export function parseEventField(raw) {
     if (raw.config !== undefined && !isPlainObject(raw.config)) {
         return { ok: false, message: "event.config must be an object" };
     }
+    const match = isPlainObject(raw.match) ? raw.match : undefined;
+    const actionError = githubMatchActionError(raw.source, match);
+    if (actionError !== undefined) {
+        return { ok: false, message: actionError };
+    }
     return {
         ok: true,
         value: {
             source: raw.source,
-            ...(isPlainObject(raw.match) ? { match: raw.match } : {}),
+            ...(match !== undefined ? { match } : {}),
             ...(isPlainObject(raw.config) ? { config: raw.config } : {}),
         },
     };

package/dist/config/ensureCatalogScanRoot.d.ts

@@ -1,6 +1,8 @@
 import type { CatalogRootKind } from "./resolveCatalogRoots.js";
 /** Directory scanned for workshop-authored pipelines and tasks. */
 export declare const WORKSHOP_PACKAGE_ROOT = "workshop";
+/** Directory the Guide always uses for pipeline packages and their stage files. */
+export declare const GUIDE_PIPELINES_ROOT = "pipelines";
 export declare function normalizeCatalogDir(directory: string): string;
 /** Untitled workshop saves land here so Run can see them without a new catalog edit. */
 export declare function defaultWorkshopPackageDirectory(pipelineId: string | undefined, catalogRootKind?: CatalogRootKind): string;

package/dist/config/ensureCatalogScanRoot.js

@@ -3,6 +3,8 @@ import { isSeq, parseDocument } from "yaml";
 import { manifestPathForProject } from "./loadStageflowManifest.js";
 /** Directory scanned for workshop-authored pipelines and tasks. */
 export const WORKSHOP_PACKAGE_ROOT = "workshop";
+/** Directory the Guide always uses for pipeline packages and their stage files. */
+export const GUIDE_PIPELINES_ROOT = "pipelines";
 export function normalizeCatalogDir(directory) {
     return directory.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
 }
@@ -30,6 +32,10 @@ export function catalogScanRootForDirectory(directory) {
         normalized.startsWith(`${WORKSHOP_PACKAGE_ROOT}/`)) {
         return WORKSHOP_PACKAGE_ROOT;
     }
+    if (normalized === GUIDE_PIPELINES_ROOT ||
+        normalized.startsWith(`${GUIDE_PIPELINES_ROOT}/`)) {
+        return GUIDE_PIPELINES_ROOT;
+    }
     return normalized;
 }
 function isCovered(entries, root) {

package/dist/config/evalCatalog.js

@@ -1,5 +1,6 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { isInsideProjectRoot } from "./catalogRelativePath.js";
 import { getModelCatalog } from "../models/catalog.js";
 import { loadDatasetFile } from "./loadDataset.js";
 import { loadEvalOutcome, resolveEvalPaths } from "./loadEval.js";
@@ -15,8 +16,35 @@ async function listFiles(manifest, kind) {
 export function listEvalFiles(manifest) {
     return listFiles(manifest, "eval");
 }
-export function listDatasetFiles(manifest) {
-    return listFiles(manifest, "dataset");
+export async function listDatasetFiles(manifest) {
+    const scanned = await listFiles(manifest, "dataset");
+    const referenced = await datasetsReferencedByEvals(manifest, scanned);
+    return [...scanned, ...referenced].sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+}
+async function datasetsReferencedByEvals(manifest, scanned) {
+    const seen = new Set(scanned.map((ref) => path.resolve(ref.absPath)));
+    const extra = [];
+    for (const ref of await listFiles(manifest, "eval")) {
+        const outcome = await loadEvalOutcome(ref.absPath, manifest.projectRoot);
+        if (!outcome.ok)
+            continue;
+        const abs = path.resolve(resolveEvalPaths(outcome.value.file, outcome.value.path).datasetPath);
+        if (seen.has(abs) || !isInsideProjectRoot(manifest.projectRoot, abs))
+            continue;
+        try {
+            if (!(await stat(abs)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        seen.add(abs);
+        extra.push({
+            absPath: abs,
+            relPath: path.relative(manifest.projectRoot, abs).split(path.sep).join("/"),
+        });
+    }
+    return extra;
 }
 export async function loadEvalCatalog(manifest, options = {}) {
     const refs = await listEvalFiles(manifest);

package/dist/config/githubTriggerAction.d.ts

@@ -0,0 +1,8 @@
+export declare const GITHUB_TRIGGER_ACTIONS: readonly ["opened", "synchronize", "updated", "merged", "closed"];
+export type GithubTriggerAction = (typeof GITHUB_TRIGGER_ACTIONS)[number];
+export declare function isGithubTriggerAction(value: unknown): value is GithubTriggerAction;
+/**
+ * For `event.source` values starting with `github.`, `match.action` must be set
+ * to one of the five PR poll actions. Returns an error message or undefined.
+ */
+export declare function githubMatchActionError(source: string, match: Record<string, unknown> | undefined): string | undefined;

package/dist/config/githubTriggerAction.js

@@ -0,0 +1,29 @@
+export const GITHUB_TRIGGER_ACTIONS = [
+    "opened",
+    "synchronize",
+    "updated",
+    "merged",
+    "closed",
+];
+const ACTION_SET = new Set(GITHUB_TRIGGER_ACTIONS);
+export function isGithubTriggerAction(value) {
+    return typeof value === "string" && ACTION_SET.has(value);
+}
+/**
+ * For `event.source` values starting with `github.`, `match.action` must be set
+ * to one of the five PR poll actions. Returns an error message or undefined.
+ */
+export function githubMatchActionError(source, match) {
+    if (!source.startsWith("github."))
+        return undefined;
+    const action = match?.action;
+    if (action === undefined) {
+        return ("event.match.action is required for github.* sources " +
+            `(one of: ${GITHUB_TRIGGER_ACTIONS.join(", ")})`);
+    }
+    if (!isGithubTriggerAction(action)) {
+        return (`event.match.action must be one of: ${GITHUB_TRIGGER_ACTIONS.join(", ")} ` +
+            `(got ${JSON.stringify(action)})`);
+    }
+    return undefined;
+}

package/dist/config/hostConfig.js

@@ -28,6 +28,7 @@ export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_READ_TOKEN_FILE",
     "STAGEFLOW_ALLOW_UNKNOWN_CONFIG",
     "STAGEFLOW_EVALS_KEEP_WORKDIR",
+    "STAGEFLOW_SHOW_INTERNAL_AGENTS",
     "STAGEFLOW_MAX_CONCURRENT_RUNS",
     "STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT",
     "STAGEFLOW_MAX_QUEUED",
@@ -59,6 +60,7 @@ export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_STAGE_EXECUTION",
     "STAGEFLOW_STAGE_CONTAINER_IMAGE",
     "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN",
+    "STAGEFLOW_STAGE_READONLY_DIR",
     "STAGEFLOW_STAGE_ENV_ALLOW",
     "STAGEFLOW_STAGE_ENV_PASSTHROUGH",
     "STAGEFLOW_GC_INTERVAL_MS",

package/dist/config/loadEval.js

@@ -74,6 +74,7 @@ const TOP_KEYS = [
 ];
 const TARGET_KEYS = ["kind", "pipeline", "stage", "file"];
 const AGENT_TARGET_KEYS = ["kind", "agent"];
+const INTERNAL_AGENT_TARGET_KEYS = ["kind", "profile"];
 const CONVERSATION_KEYS = [
     "mode",
     "max_turns",
@@ -188,13 +189,15 @@ function parseTarget(c, raw) {
         return undefined;
     }
     if (raw.kind === undefined) {
-        c.add("eval.invalid_field", `target "kind" is required ("stage" or "agent")`);
+        c.add("eval.invalid_field", `target "kind" is required ("stage", "agent" or "internal_agent")`);
         return undefined;
     }
     if (raw.kind === "agent")
         return parseAgentTarget(c, raw);
+    if (raw.kind === "internal_agent")
+        return parseInternalAgentTarget(c, raw);
     if (raw.kind !== "stage") {
-        c.add("eval.target_kind_unsupported", `target kind ${JSON.stringify(raw.kind)} is not supported (only "stage" and "agent")`);
+        c.add("eval.target_kind_unsupported", `target kind ${JSON.stringify(raw.kind)} is not supported (only "stage", "agent" and "internal_agent")`);
         return undefined;
     }
     if (raw.agent !== undefined) {
@@ -251,6 +254,21 @@ function parseAgentTarget(c, raw) {
     }
     return { kind: "agent", agent };
 }
+function parseInternalAgentTarget(c, raw) {
+    for (const key of ["agent", "pipeline", "stage", "file"]) {
+        if (raw[key] !== undefined) {
+            c.add("eval.target_invalid", `target "${key}" is not valid with kind: internal_agent; use "profile"`);
+            return undefined;
+        }
+    }
+    c.unknownKeys(raw, INTERNAL_AGENT_TARGET_KEYS, "target");
+    const profile = raw.profile;
+    if (typeof profile !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(profile)) {
+        c.add("eval.target_invalid", `target "profile" must be an internal agent id such as stageflow-guide`);
+        return undefined;
+    }
+    return { kind: "internal_agent", profile };
+}
 function parseTask(c, raw) {
     if (raw === undefined)
         return undefined;
@@ -669,7 +687,7 @@ function parseGrader(c, raw, index, defaultJudge, kind) {
                 c.add("eval.grader_invalid", `${label} "mode" must be "each_mentioned" or "equals"`);
                 ok = false;
             }
-            let pathValue = kind === "agent" ? "final_reply" : "payload";
+            let pathValue = kind === "agent" || kind === "internal_agent" ? "final_reply" : "payload";
             if (raw.path !== undefined) {
                 if (typeof raw.path === "string" && FIELD_PATH_PATTERN.test(raw.path))
                     pathValue = raw.path;

package/dist/config/pipelineNeeds.d.ts

@@ -1,6 +1,8 @@
 import type { NeedTerminalState, PipelineNeedEdge, PipelineNeedItem, PipelineNeeds, PipelineRoute, PipelineRouteForwardEntry, ResolvedPipelineStageNode } from "../types/pipeline.js";
 export declare const NEED_TERMINAL_STATES: readonly NeedTerminalState[];
 export declare function isNeedTerminalState(value: unknown): value is NeedTerminalState;
+/** Map known aliases; return undefined if not a terminal state or known alias. */
+export declare function canonicalizeNeedTerminalState(value: unknown): NeedTerminalState | undefined;
 export declare function parsePipelineNeeds(raw: unknown, stageId: string): {
     ok: true;
     value: PipelineNeeds;

package/dist/config/pipelineNeeds.js

@@ -5,9 +5,21 @@ export const NEED_TERMINAL_STATES = [
     "skipped",
 ];
 const NEED_TERMINAL_STATE_SET = new Set(NEED_TERMINAL_STATES);
+const NEED_TERMINAL_ALIASES = {
+    success: "succeeded",
+    failure: "failed",
+};
 export function isNeedTerminalState(value) {
     return typeof value === "string" && NEED_TERMINAL_STATE_SET.has(value);
 }
+/** Map known aliases; return undefined if not a terminal state or known alias. */
+export function canonicalizeNeedTerminalState(value) {
+    if (typeof value !== "string")
+        return undefined;
+    if (isNeedTerminalState(value))
+        return value;
+    return NEED_TERMINAL_ALIASES[value];
+}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -21,14 +33,15 @@ function parseNeedOn(raw, stageId, parentId) {
     const seen = new Set();
     const on = [];
     for (const item of raw) {
-        if (typeof item !== "string" || !NEED_TERMINAL_STATE_SET.has(item) || seen.has(item)) {
+        const canonical = canonicalizeNeedTerminalState(item);
+        if (canonical === undefined || seen.has(canonical)) {
             return {
                 ok: false,
                 message: `stage "${stageId}": needs "${parentId}": on must be a non-empty unique subset of succeeded, failed, skipped`,
             };
         }
-        seen.add(item);
-        on.push(item);
+        seen.add(canonical);
+        on.push(canonical);
     }
     return { ok: true, value: on };
 }

package/dist/config/pipelineRoute.js

@@ -1,4 +1,4 @@
-import { isNeedTerminalState } from "./pipelineNeeds.js";
+import { canonicalizeNeedTerminalState } from "./pipelineNeeds.js";
 import { parseRouteIf } from "./routeIf.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -81,14 +81,15 @@ function parseRouteOn(raw, stageId, targetId) {
     const seen = new Set();
     const on = [];
     for (const item of items) {
-        if (typeof item !== "string" || !isNeedTerminalState(item) || seen.has(item)) {
+        const canonical = canonicalizeNeedTerminalState(item);
+        if (canonical === undefined || seen.has(canonical)) {
             return {
                 ok: false,
                 message: `stage "${stageId}": route "${targetId}": on must be a non-empty unique subset of succeeded, failed, skipped`,
             };
         }
-        seen.add(item);
-        on.push(item);
+        seen.add(canonical);
+        on.push(canonical);
     }
     return { ok: true, value: on };
 }

package/dist/config/validateCatalog.d.ts

@@ -4,7 +4,7 @@ import type { LoadIssue } from "./loadOutcome.js";
 import type { AnyChannelProvider } from "../channels/types.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task" | "trigger" | "eval" | "dataset";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.stage_wrapper_skill_rejected" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "pipeline.invalid_channels" | "pipeline.invalid_memories" | "pipeline.memory_unavailable" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_channels" | "stage.channel_unavailable" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.stage_wrapper_skill_rejected" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "pipeline.invalid_channels" | "pipeline.invalid_memories" | "pipeline.memory_unavailable" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_channels" | "stage.channel_unavailable" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "trigger.github_action_required" | "trigger.invalid_github_action" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;

package/dist/config/validateCatalog.js

@@ -6,6 +6,7 @@ import { INLINE_PIPELINE_PATH, loadPipelineFromObjectOutcome, loadPipelineOutcom
 import { loadStageOutcome } from "./loadStage.js";
 import { loadTaskOutcome } from "./loadTask.js";
 import { loadTriggerOutcome } from "./loadTrigger.js";
+import { githubMatchActionError, isGithubTriggerAction } from "./githubTriggerAction.js";
 import { loadEvalCatalog } from "./evalCatalog.js";
 import { evalFindingsFromIssues } from "./validateEval.js";
 import { readYamlObject } from "./readYamlObject.js";
@@ -666,6 +667,17 @@ export function findingsForTriggerRefs(cwd, absPath, trigger, refs) {
     if (trigger.task !== undefined && !refs.taskIds.has(trigger.task)) {
         findings.push(findingTriggerError(cwd, absPath, `Trigger "${trigger.id}" references unknown task "${trigger.task}"`, "trigger.unknown_task"));
     }
+    const source = trigger.event?.source;
+    if (typeof source === "string" && source.startsWith("github.")) {
+        const action = trigger.event?.match?.action;
+        if (action === undefined) {
+            findings.push(findingTriggerError(cwd, absPath, `Trigger "${trigger.id}" requires event.match.action for github.* sources`, "trigger.github_action_required"));
+        }
+        else if (!isGithubTriggerAction(action)) {
+            findings.push(findingTriggerError(cwd, absPath, githubMatchActionError(source, trigger.event?.match) ??
+                `Trigger "${trigger.id}" has an invalid event.match.action`, "trigger.invalid_github_action"));
+        }
+    }
     return findings;
 }
 async function validateSingleTask(invocationCwd, taskArg) {