stageflow 0.25.0 → 0.30.0

package/dist/runtime/stageWorker.js

@@ -1,16 +1,21 @@
 import { resolveAgentPort } from "../agent/resolveAgentPort.js";
 import { asAgentBackendId } from "../agent/agentBackend.js";
 import { loadStageflowManifestOutcome } from "../config/loadStageflowManifest.js";
+import { loadNamedSecretsFromAttemptDir } from "../logging/namedSecrets.js";
 import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
+import { attemptWorkspaceDir } from "../runstore/workspaceLayout.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { loadRunContext } from "./resumeReconstruct.js";
-import { bindPiAgentDirEnv, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
+import { bindPiAgentDirEnv, overlayStageBindingEnv, rootsForStageWorker, stageBindingEnvFromRun, withResolvedAuthPath, } from "./stageRoots.js";
+import { buildStageEnvironment } from "./stageEnvironment.js";
+import { ensureStageCacheDirs } from "./stageCacheEnv.js";
+import { PACKAGE_VERSION } from "../package-meta.js";
 import { runStage, isRunStageWaiting, } from "./stageRunner.js";
 import { openStageAttempt } from "./stageAttemptBootstrap.js";
 import { attemptContext } from "./stageAttemptContext.js";
 import { loadActiveFeedbackLoopContext } from "./feedbackLoopCoordinator.js";
-import { outcomeToWorkerResult, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
+import { outcomeToWorkerResult, SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 export async function runStageWorker(input) {
     const store = createRunStore({ rootDir: globalStageflowHome() });
     const { meta, task, loaded } = await loadRunContext(store, input.runId, input.rootDir);
@@ -33,8 +38,29 @@ export async function runStageWorker(input) {
     });
     const workspaceDir = store.getWorkspaceDir(input.runId);
     const checkoutRoot = meta.checkout_root;
+    const binding = input.env !== undefined
+        ? {
+            env: input.env,
+            kind: input.bindingKind ?? "unbound",
+        }
+        : stageBindingEnvFromRun({
+            meta,
+            task,
+            runWorkspaceDir: workspaceDir,
+            hostEnv: process.env,
+        });
+    const baseEnv = process.env[SF_STAGE_WORKER] === "1"
+        ? Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined))
+        : buildStageEnvironment({
+            hostEnv: process.env,
+            cacheVars: ensureStageCacheDirs(),
+            packageVersion: PACKAGE_VERSION,
+        }).env;
+    const stageEnv = Object.fromEntries(Object.entries(overlayStageBindingEnv(baseEnv, binding.env, binding.kind))
+        .filter((e) => e[1] !== undefined));
     const mode = input.mode ?? "run";
     const attempt = input.attempt ?? 1;
+    loadNamedSecretsFromAttemptDir(attemptWorkspaceDir(workspaceDir, input.stageId, attempt));
     const attemptCtx = input.attempt !== undefined ? attemptContext(input.attempt) : undefined;
     const eventOptions = { attempt };
     const roots = withResolvedAuthPath(rootsForStageWorker(workspaceDir, input.stageId, stage.model, checkoutRoot, attemptCtx), input.rootDir);
@@ -57,6 +83,7 @@ export async function runStageWorker(input) {
                 roots,
                 resumeToken: input.sessionFilePath,
                 sessionMode: "waiting_resume",
+                stageEnv,
                 onActivity: (event) => {
                     void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
                 },
@@ -83,6 +110,7 @@ export async function runStageWorker(input) {
                 factoryCwd: input.rootDir,
                 operatorCatalog: input.operatorCatalog,
                 skipGates: input.skipGates,
+                stageEnv,
             });
             return outcome;
         }
@@ -116,6 +144,7 @@ export async function runStageWorker(input) {
                 ...(resumeToken !== undefined ? { resumeToken } : {}),
                 sessionMode: mode,
                 ...(feedbackLoopContext !== undefined ? { feedbackLoopContext } : {}),
+                stageEnv,
                 onActivity: (event) => {
                     void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
                 },
@@ -140,6 +169,7 @@ export async function runStageWorker(input) {
                 factoryCwd: input.rootDir,
                 operatorCatalog: input.operatorCatalog,
                 skipGates: input.skipGates,
+                stageEnv,
             });
         }
         return runStage({
@@ -158,6 +188,7 @@ export async function runStageWorker(input) {
             factoryCwd: input.rootDir,
             operatorCatalog: input.operatorCatalog,
             skipGates: input.skipGates,
+            stageEnv,
         });
     }
     finally {
@@ -165,18 +196,35 @@ export async function runStageWorker(input) {
     }
 }
 export function sendWorkerResult(result) {
-    if (typeof process.send === "function") {
-        process.send(result);
+    if (typeof process.send !== "function") {
+        return Promise.resolve();
     }
+    return new Promise((resolve) => {
+        try {
+            const ok = process.send(result, (err) => {
+                void err;
+                resolve();
+            });
+            if (ok === false) {
+                resolve();
+            }
+        }
+        catch {
+            resolve();
+        }
+    });
 }
-export function exitForOutcome(outcome) {
-    const message = outcomeToWorkerResult(outcome);
-    sendWorkerResult(message);
+export function exitCodeForOutcome(outcome) {
     if (isRunStageWaiting(outcome)) {
-        process.exit(STAGE_WORKER_EXIT.WAITING);
+        return STAGE_WORKER_EXIT.WAITING;
     }
     if (outcome.ok) {
-        process.exit(STAGE_WORKER_EXIT.SUCCEEDED);
+        return STAGE_WORKER_EXIT.SUCCEEDED;
     }
-    process.exit(STAGE_WORKER_EXIT.FAILED);
+    return STAGE_WORKER_EXIT.FAILED;
+}
+export async function exitForOutcome(outcome) {
+    const message = outcomeToWorkerResult(outcome);
+    await sendWorkerResult(message);
+    return exitCodeForOutcome(outcome);
 }

package/dist/runtime/stageWorkerProtocol.d.ts

@@ -1,11 +1,14 @@
 import type { RunStageOutcome } from "./stageRunner.js";
 import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
+import type { DerivedBindingKind } from "./stageRoots.js";
 export declare const SF_STAGE_WORKER = "SF_STAGE_WORKER";
 export declare const STAGE_WORKER_EXIT: {
     readonly SUCCEEDED: 0;
     readonly FAILED: 1;
     readonly WAITING: 2;
 };
+export declare const PROCESS_EXIT_FORCE_MS = 1000;
+export declare function scheduleExitWithDrain(code: number): void;
 export type StageWorkerInput = {
     runId: string;
     stageId: string;
@@ -16,6 +19,8 @@ export type StageWorkerInput = {
     sessionFilePath?: string;
     operatorCatalog?: OperatorCatalog;
     skipGates?: boolean;
+    env?: Record<string, string>;
+    bindingKind?: DerivedBindingKind;
 };
 export type StageWorkerResult = {
     type: "succeeded";

package/dist/runtime/stageWorkerProtocol.js

@@ -4,6 +4,14 @@ export const STAGE_WORKER_EXIT = {
     FAILED: 1,
     WAITING: 2,
 };
+export const PROCESS_EXIT_FORCE_MS = 1_000;
+export function scheduleExitWithDrain(code) {
+    process.exitCode = code;
+    const timer = setTimeout(() => {
+        process.exit(code);
+    }, PROCESS_EXIT_FORCE_MS);
+    timer.unref();
+}
 export function outcomeToWorkerResult(outcome) {
     if ("waiting" in outcome && outcome.waiting) {
         return { type: "waiting" };

package/dist/runtime/startPayload.d.ts

@@ -0,0 +1,32 @@
+import type { InlinePipelineDefinition } from "../types/pipeline.js";
+/** Cap for inline pipeline body + skills start payload (1 MiB). */
+export declare const START_PAYLOAD_MAX_BYTES = 1048576;
+export declare const START_TOKEN_REJECTED: "start.token_rejected";
+export declare const INLINE_PIPELINE_TOO_LARGE: "inline_pipeline_too_large";
+export type PipelinePersistenceFields = {
+    pipelineSource: "inline" | "path";
+    pipelineBody?: string;
+};
+export declare function pipelineBodyBytes(fields: PipelinePersistenceFields): number;
+export type PipelinePersistenceResult = {
+    ok: true;
+    fields: PipelinePersistenceFields;
+} | {
+    ok: false;
+    code: typeof INLINE_PIPELINE_TOO_LARGE;
+    bytes: number;
+    maxBytes: number;
+};
+export declare function pipelinePersistenceForStart(pipeline: string | InlinePipelineDefinition): PipelinePersistenceResult;
+/** MCP prefers `checkout`; `checkout_override` remains a temporary alias. */
+export declare function pickCheckoutOverride(args: {
+    checkout?: string;
+    checkout_override?: string;
+}): string | undefined;
+export declare function isTokenShapedKey(key: string): boolean;
+export declare function findTokenShapedField(value: unknown, pathPrefix?: string): string | undefined;
+export declare function tokenRejectedPayload(field: string): {
+    error: string;
+    code: typeof START_TOKEN_REJECTED;
+    field: string;
+};

package/dist/runtime/startPayload.js

@@ -0,0 +1,59 @@
+/** Cap for inline pipeline body + skills start payload (1 MiB). */
+export const START_PAYLOAD_MAX_BYTES = 1_048_576;
+export const START_TOKEN_REJECTED = "start.token_rejected";
+export const INLINE_PIPELINE_TOO_LARGE = "inline_pipeline_too_large";
+export function pipelineBodyBytes(fields) {
+    if (fields.pipelineBody === undefined)
+        return 0;
+    return Buffer.byteLength(fields.pipelineBody, "utf8");
+}
+export function pipelinePersistenceForStart(pipeline) {
+    if (typeof pipeline === "string") {
+        return { ok: true, fields: { pipelineSource: "path" } };
+    }
+    const body = JSON.stringify(pipeline);
+    const bytes = Buffer.byteLength(body, "utf8");
+    if (bytes > START_PAYLOAD_MAX_BYTES) {
+        return {
+            ok: false,
+            code: INLINE_PIPELINE_TOO_LARGE,
+            bytes,
+            maxBytes: START_PAYLOAD_MAX_BYTES,
+        };
+    }
+    return {
+        ok: true,
+        fields: { pipelineSource: "inline", pipelineBody: body },
+    };
+}
+/** MCP prefers `checkout`; `checkout_override` remains a temporary alias. */
+export function pickCheckoutOverride(args) {
+    return args.checkout ?? args.checkout_override;
+}
+const TOKEN_SHAPED_KEY = /^(token|github_token|gh_token|access_token|personal_access_token|pat|clone_token|git_token|api_token|auth_token)$/i;
+export function isTokenShapedKey(key) {
+    return TOKEN_SHAPED_KEY.test(key);
+}
+export function findTokenShapedField(value, pathPrefix = "") {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const path = pathPrefix ? `${pathPrefix}.${key}` : key;
+        if (isTokenShapedKey(key))
+            return path;
+        if (key === "task" && child !== null && typeof child === "object") {
+            const nested = findTokenShapedField(child, path);
+            if (nested !== undefined)
+                return nested;
+        }
+    }
+    return undefined;
+}
+export function tokenRejectedPayload(field) {
+    return {
+        error: `Clone credentials must stay on the Host; reject token-shaped start field "${field}"`,
+        code: START_TOKEN_REJECTED,
+        field,
+    };
+}

package/dist/runtime/taskInput.js

@@ -1,11 +1,11 @@
 import path from "node:path";
 import { stringify as stringifyYaml } from "yaml";
-import { parseTaskFile } from "../config/loadTask.js";
+import { coerceTaskFile } from "../config/loadTask.js";
 import { relPath } from "../config/validateCatalog.js";
 import { payloadInstanceMismatch } from "../envelope/payloadSchema.js";
 import { resolveTaskPath } from "./pipelineRunner.js";
 export function isTaskFile(value) {
-    return parseTaskFile(value, "task").ok;
+    return coerceTaskFile(value) !== undefined;
 }
 export function taskFileToYaml(task) {
     const doc = {
@@ -18,6 +18,15 @@ export function taskFileToYaml(task) {
         doc.constraints = task.constraints;
     if (task.checkout !== undefined)
         doc.checkout = task.checkout;
+    if (task.repository !== undefined)
+        doc.repository = task.repository;
+    if (task.ref !== undefined)
+        doc.ref = task.ref;
+    if (task.run_branch_template !== undefined) {
+        doc.run_branch_template = task.run_branch_template;
+    }
+    if (task.git_identity !== undefined)
+        doc.git_identity = task.git_identity;
     if (task.input !== undefined)
         doc.input = task.input;
     return stringifyYaml(doc);
@@ -78,9 +87,9 @@ export function resolveStartTaskInput(input, cwd) {
         }
         return { kind: "path", taskPath: resolveTaskPath(input.task, cwd) };
     }
-    const parsed = parseTaskFile(input.task, "task");
-    if (parsed.ok) {
-        return { kind: "yaml", taskYaml: taskFileToYaml(parsed.value) };
+    const coerced = coerceTaskFile(input.task);
+    if (coerced !== undefined) {
+        return { kind: "yaml", taskYaml: taskFileToYaml(coerced) };
     }
     throw new Error("task path, task object, or taskYaml is required");
 }

package/dist/runtime/triggerCatalog.d.ts

@@ -0,0 +1,6 @@
+import type { TriggerFile } from "../types/trigger.js";
+export declare function findCatalogPathById(paths: string[], id: string): Promise<string | undefined>;
+export declare function findTriggerDefinition(triggerPaths: string[], triggerId: string): Promise<{
+    path: string;
+    definition: TriggerFile;
+} | undefined>;

package/dist/runtime/triggerCatalog.js

@@ -0,0 +1,24 @@
+import { readYamlObject } from "../config/readYamlObject.js";
+import { loadTriggerOutcome } from "../config/loadTrigger.js";
+export async function findCatalogPathById(paths, id) {
+    for (const filePath of paths) {
+        try {
+            const raw = await readYamlObject(filePath);
+            if (raw?.id === id)
+                return filePath;
+        }
+        catch {
+            // Unreadable/invalid catalog files are surfaced by `sf validate`; skip here.
+        }
+    }
+    return undefined;
+}
+export async function findTriggerDefinition(triggerPaths, triggerId) {
+    for (const filePath of triggerPaths) {
+        const outcome = await loadTriggerOutcome(filePath);
+        if (outcome.ok && outcome.value.id === triggerId) {
+            return { path: filePath, definition: outcome.value };
+        }
+    }
+    return undefined;
+}

package/dist/runtime/triggerEventMatch.d.ts

@@ -0,0 +1,2 @@
+/** Subset-match: every key/value in `match` must equal-match `payload`. No `match` matches everything. */
+export declare function matchesEventFilter(match: Record<string, unknown> | undefined, payload: Record<string, unknown>): boolean;

package/dist/runtime/triggerEventMatch.js

@@ -0,0 +1,6 @@
+/** Subset-match: every key/value in `match` must equal-match `payload`. No `match` matches everything. */
+export function matchesEventFilter(match, payload) {
+    if (!match)
+        return true;
+    return Object.entries(match).every(([key, value]) => payload[key] === value);
+}

package/dist/runtime/triggerPort.d.ts

@@ -0,0 +1,14 @@
+import type { TaskFile } from "../types/task.js";
+export type TriggerFireEvent = {
+    triggerId: string;
+    task?: TaskFile;
+};
+/**
+ * Abstract seam for anything that decides "fire trigger X now" — a croner-backed
+ * schedule loop, a GitHub/email poller, a webhook receiver. No adapter implements
+ * this yet; it exists so those later adapters build against a locked contract.
+ */
+export interface TriggerSourcePort {
+    start(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/runtime/triggerPort.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/triggerRunner.d.ts

@@ -0,0 +1,17 @@
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager, StartRunResult } from "./runManager.js";
+import type { TaskFile } from "../types/task.js";
+/**
+ * Resolves a trigger id to its `*.trigger.yaml` catalog definition, resolves its
+ * `pipeline`/`task` refs to catalog files, and starts a real run through
+ * `RunManager.startRun` — the same internal entry point the CLI/MCP/console use.
+ * On a successful start, records the fire on the trigger's store row.
+ *
+ * `task` presence on the trigger definition is the either/or mode switch: a
+ * catalog-mode trigger (`task` set) rejects a supplied `options.task`; a
+ * dynamic-mode trigger (`task` absent) requires one.
+ */
+export declare function fireTrigger(triggerId: string, store: RunStore, runManager: RunManager, options?: {
+    cwd?: string;
+    task?: TaskFile;
+}): Promise<StartRunResult>;

package/dist/runtime/triggerRunner.js

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { getCatalogScanPaths } from "../config/browseCatalog.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { findCatalogPathById, findTriggerDefinition } from "./triggerCatalog.js";
+/**
+ * Resolves a trigger id to its `*.trigger.yaml` catalog definition, resolves its
+ * `pipeline`/`task` refs to catalog files, and starts a real run through
+ * `RunManager.startRun` — the same internal entry point the CLI/MCP/console use.
+ * On a successful start, records the fire on the trigger's store row.
+ *
+ * `task` presence on the trigger definition is the either/or mode switch: a
+ * catalog-mode trigger (`task` set) rejects a supplied `options.task`; a
+ * dynamic-mode trigger (`task` absent) requires one.
+ */
+export async function fireTrigger(triggerId, store, runManager, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return { ok: false, reason: "No Stageflow catalog found", status: 404 };
+    }
+    const found = await findTriggerDefinition(scanPaths.triggerPaths, triggerId);
+    if (!found) {
+        return { ok: false, reason: `Trigger not found: ${triggerId}`, status: 404 };
+    }
+    const { path: triggerPath, definition: trigger } = found;
+    if (!trigger.enabled) {
+        return { ok: false, reason: `Trigger is disabled: ${triggerId}`, status: 409 };
+    }
+    const suppliedTask = options.task;
+    if (trigger.task !== undefined && suppliedTask !== undefined) {
+        return {
+            ok: false,
+            reason: `Trigger "${triggerId}" already has a catalog task "${trigger.task}"; task override is not allowed`,
+            status: 422,
+            code: "trigger.task_override_not_allowed",
+        };
+    }
+    if (trigger.task === undefined && suppliedTask === undefined) {
+        return {
+            ok: false,
+            reason: `Trigger "${triggerId}" has no catalog task; a task must be supplied when firing`,
+            status: 422,
+            code: "trigger.task_required",
+        };
+    }
+    const pipelinePath = await findCatalogPathById(scanPaths.pipelinePaths, trigger.pipeline);
+    if (!pipelinePath) {
+        return {
+            ok: false,
+            reason: `Trigger "${triggerId}" references unknown pipeline "${trigger.pipeline}"`,
+            status: 400,
+        };
+    }
+    let taskInput;
+    if (trigger.task !== undefined) {
+        const taskPath = await findCatalogPathById(scanPaths.taskPaths, trigger.task);
+        if (!taskPath) {
+            return {
+                ok: false,
+                reason: `Trigger "${triggerId}" references unknown task "${trigger.task}"`,
+                status: 400,
+            };
+        }
+        taskInput = taskPath;
+    }
+    else {
+        taskInput = suppliedTask;
+    }
+    const projectRoot = ctx.projectRoot ?? undefined;
+    const definitionRef = projectRoot !== undefined
+        ? path.relative(projectRoot, triggerPath).replace(/\\/g, "/")
+        : triggerPath;
+    await store.upsertTrigger({
+        id: triggerId,
+        definitionRef,
+        enabled: trigger.enabled,
+    });
+    const started = await runManager.startRun({
+        pipeline: pipelinePath,
+        task: taskInput,
+        ...(projectRoot !== undefined ? { projectRoot } : {}),
+    });
+    if (started.ok) {
+        await store.recordTriggerFired(triggerId, started.runId);
+    }
+    return started;
+}

package/dist/runtime/verifiedStageExecution.d.ts

@@ -2,6 +2,8 @@ import type { StageRunResult } from "../agent/port.js";
 import type { RunStore } from "../runstore/port.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
 import type { StageConfig } from "../types/stage.js";
+import type { BrowserRunner } from "../browser/browserHost.js";
+import { type LoginCheckConfig, type LoginCheckOptions } from "../browser/loginCheck.js";
 import type { StageRoots } from "./stageRoots.js";
 /** Sidecar written before completion command checks so they can inspect fork_choice. */
 export declare const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
@@ -28,4 +30,10 @@ export declare function createVerifiedStageExecution(options: {
     stage: StageConfig;
     dag?: ResolvedPipelineDag;
     roots: StageRoots;
+    commandEnv?: NodeJS.ProcessEnv;
+    browserLogin?: {
+        check: LoginCheckConfig;
+        runner?: BrowserRunner;
+        options?: LoginCheckOptions;
+    };
 }): VerifiedStageExecution;

package/dist/runtime/verifiedStageExecution.js

@@ -9,6 +9,9 @@ import { COMPLETION_VERIFICATION_FAILURE_PREFIX, } from "../types/completion.js"
 import { runCompletionContract, } from "./completionCheckRunner.js";
 import { readCompletionCheckoutBaseline, writeCompletionCheckoutBaseline, } from "./completionCheckoutBaseline.js";
 import { createGitCheckoutCapability } from "./gitCheckoutCapability.js";
+import { readStagePersistedBrowserEnv } from "../browser/stageBrowserEnv.js";
+import { defaultBrowserRunner } from "../browser/browserTeardown.js";
+import { runLoginCheck, } from "../browser/loginCheck.js";
 /** Sidecar written before completion command checks so they can inspect fork_choice. */
 export const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
 export function completionVerificationFailureReason(failedCheckIds) {
@@ -42,7 +45,7 @@ function gateDecisionsForAttempt(options) {
  * module in stageRunner.
  */
 export function createVerifiedStageExecution(options) {
-    const { store, runId, stageId, attempt, stage, dag, roots } = options;
+    const { store, runId, stageId, attempt, stage, dag, roots, commandEnv } = options;
     const contract = dag?.nodes.find((node) => node.id === stageId)?.completion;
     let checkout;
     let checkoutBefore;
@@ -82,11 +85,23 @@ export function createVerifiedStageExecution(options) {
                     payloadSchema: stage.payload_schema,
                     artifactsDir,
                     commandWorkingDirectory: roots.cwd,
+                    ...(commandEnv !== undefined ? { commandEnv } : {}),
                     gates: gateDecisionsForAttempt({ store, runId, stageId, attempt }),
                     checkout,
                     checkoutBefore,
                     checkoutError,
                     checklistAttestations: candidate.envelope.checklist_attestations,
+                    ...(options.browserLogin !== undefined
+                        ? {
+                            browserLogin: async () => {
+                                const env = await readStagePersistedBrowserEnv(roots.runWorkspaceDir, stageId);
+                                if (env === undefined) {
+                                    throw new Error("browser session env is missing for this stage");
+                                }
+                                return runLoginCheck(env, options.browserLogin.check, options.browserLogin.runner ?? defaultBrowserRunner, options.browserLogin.options);
+                            },
+                        }
+                        : {}),
                     onCheckStart: async (check) => {
                         await store.upsertVerificationCheckResult(runId, stageId, {
                             check_id: check.id,

package/dist/runtime/webhookSignature.d.ts

@@ -0,0 +1 @@
+export declare function verifyHmacSignature(rawBody: Buffer, headerValue: string, secret: string, scheme: "hex" | "base64"): boolean;

package/dist/runtime/webhookSignature.js

@@ -0,0 +1,12 @@
+import crypto from "node:crypto";
+export function verifyHmacSignature(rawBody, headerValue, secret, scheme) {
+    const eqIndex = headerValue.indexOf("=");
+    const hasPrefix = eqIndex !== -1 && eqIndex < headerValue.length - 1;
+    const provided = hasPrefix ? headerValue.slice(eqIndex + 1) : headerValue;
+    const computed = crypto.createHmac("sha256", secret).update(rawBody).digest(scheme);
+    const providedBuffer = Buffer.from(provided, scheme);
+    const computedBuffer = Buffer.from(computed, scheme);
+    if (providedBuffer.length !== computedBuffer.length)
+        return false;
+    return crypto.timingSafeEqual(providedBuffer, computedBuffer);
+}

package/dist/runtime/workspaceBinding.d.ts

@@ -0,0 +1,20 @@
+import { type LoadOutcome } from "../config/loadOutcome.js";
+export type WorkspaceBinding = {
+    kind: "repository";
+    repository: string;
+    ref: string;
+} | {
+    kind: "checkout";
+    path: string;
+} | {
+    kind: "unbound";
+};
+export type WorkspaceBindingInput = {
+    repository?: string;
+    ref?: string;
+    checkout?: string;
+};
+export type ResolveWorkspaceBindingOptions = {
+    checkoutOverride?: string;
+};
+export declare function resolveWorkspaceBinding(task: WorkspaceBindingInput, options?: ResolveWorkspaceBindingOptions): LoadOutcome<WorkspaceBinding>;

package/dist/runtime/workspaceBinding.js

@@ -0,0 +1,60 @@
+import { loadFailure, loadSuccess } from "../config/loadOutcome.js";
+const OWNER_REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function nonEmptyTrimmed(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isGithubOwnerRepo(repository) {
+    return OWNER_REPO_RE.test(repository);
+}
+export function resolveWorkspaceBinding(task, options) {
+    const repository = nonEmptyTrimmed(task.repository);
+    const ref = nonEmptyTrimmed(task.ref);
+    const checkoutPath = nonEmptyTrimmed(options?.checkoutOverride ?? task.checkout);
+    const hasRepositoryField = repository !== undefined;
+    if (hasRepositoryField && checkoutPath !== undefined) {
+        return loadFailure([
+            {
+                code: "task.binding_conflict",
+                message: "Task cannot declare both repository and checkout (exactly one workspace binding)",
+                category: "task",
+            },
+        ]);
+    }
+    if (hasRepositoryField && ref === undefined) {
+        return loadFailure([
+            {
+                code: "task.repository_ref_required",
+                message: "Task repository requires a non-empty ref",
+                category: "task",
+            },
+        ]);
+    }
+    if (ref !== undefined && repository === undefined) {
+        return loadFailure([
+            {
+                code: "task.ref_without_repository",
+                message: "Task ref requires repository",
+                category: "task",
+            },
+        ]);
+    }
+    if (repository !== undefined && ref !== undefined) {
+        if (!isGithubOwnerRepo(repository)) {
+            return loadFailure([
+                {
+                    code: "task.repository_invalid",
+                    message: "Task repository must be a GitHub owner/repo (e.g. acme/api); hosts and URLs are not accepted",
+                    category: "task",
+                },
+            ]);
+        }
+        return loadSuccess({ kind: "repository", repository, ref });
+    }
+    if (checkoutPath !== undefined) {
+        return loadSuccess({ kind: "checkout", path: checkoutPath });
+    }
+    return loadSuccess({ kind: "unbound" });
+}