stageflow 0.27.0 → 0.31.0

package/dist/runtime/settingsFile.js

@@ -5,7 +5,8 @@ import { globalStageflowHome } from "../project/globalHome.js";
 import { storeRootFor } from "../runstore/paths.js";
 export const SETTINGS_FILE_NAME = "settings.json";
 export const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
-export const INVALID_CREDENTIAL_SOURCE_MESSAGE = 'credentialSource must be "pi_home" or "sf_owned"';
+export const INVALID_CREDENTIAL_SOURCE_MESSAGE = 'credentialSource must be "sf_owned"';
+export const INVALID_WORKSHOP_MODEL_MESSAGE = "workshopModel must be a non-empty string";
 export function globalSettingsFilePath() {
     return path.join(globalStageflowHome(), SETTINGS_FILE_NAME);
 }
@@ -28,11 +29,20 @@ export function parseSlotCount(value) {
     return value;
 }
 export function parseCredentialSource(value) {
-    if (value === "pi_home" || value === "sf_owned") {
+    if (value === "sf_owned") {
         return value;
     }
+    if (value === "pi_home") {
+        return "sf_owned";
+    }
     return undefined;
 }
+export function parseWorkshopModelSetting(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
 function readRawSettingsFromFile(filePath) {
     if (!existsSync(filePath))
         return {};
@@ -60,8 +70,50 @@ function parseFactorySettingsFromRaw(raw) {
     if (credentialSource !== undefined) {
         settings.credentialSource = credentialSource;
     }
+    const workshopModel = parseWorkshopModelSetting(raw.workshopModel);
+    if (workshopModel !== undefined) {
+        settings.workshopModel = workshopModel;
+    }
     return settings;
 }
+function serializeFactorySettings(next) {
+    const out = {};
+    if (next.maxConcurrent !== undefined) {
+        out.maxConcurrent = next.maxConcurrent;
+    }
+    if (next.credentialSource !== undefined) {
+        out.credentialSource = next.credentialSource;
+    }
+    if (next.workshopModel !== undefined) {
+        out.workshopModel = next.workshopModel;
+    }
+    return out;
+}
+function applyFactorySettingsPatch(current, patch) {
+    if (patch.credentialSource !== undefined &&
+        parseCredentialSource(patch.credentialSource) === undefined) {
+        throw new Error(INVALID_CREDENTIAL_SOURCE_MESSAGE);
+    }
+    if (patch.maxConcurrent !== undefined &&
+        parseSlotCount(patch.maxConcurrent) === undefined) {
+        throw new Error(INVALID_SLOT_COUNT_MESSAGE);
+    }
+    if (patch.workshopModel !== undefined &&
+        parseWorkshopModelSetting(patch.workshopModel) === undefined) {
+        throw new Error(INVALID_WORKSHOP_MODEL_MESSAGE);
+    }
+    const next = { ...current };
+    if (patch.maxConcurrent !== undefined) {
+        next.maxConcurrent = patch.maxConcurrent;
+    }
+    if (patch.credentialSource !== undefined) {
+        next.credentialSource = patch.credentialSource;
+    }
+    if (patch.workshopModel !== undefined) {
+        next.workshopModel = parseWorkshopModelSetting(patch.workshopModel);
+    }
+    return next;
+}
 export function readCredentialSourceFromContext(ctx) {
     if (ctx.isGitProject) {
         const fromProject = parseCredentialSource(readRawSettingsFromFile(settingsFilePathForContext(ctx)).credentialSource);
@@ -84,56 +136,14 @@ function ensureSettingsDirForContext(ctx) {
     mkdirSync(path.dirname(settingsFilePathForContext(ctx)), { recursive: true });
 }
 export function writeFactorySettingsForContext(ctx, patch) {
-    if (patch.credentialSource !== undefined &&
-        parseCredentialSource(patch.credentialSource) === undefined) {
-        throw new Error(INVALID_CREDENTIAL_SOURCE_MESSAGE);
-    }
-    if (patch.maxConcurrent !== undefined &&
-        parseSlotCount(patch.maxConcurrent) === undefined) {
-        throw new Error(INVALID_SLOT_COUNT_MESSAGE);
-    }
-    const current = readFactorySettingsForContext(ctx);
-    const next = { ...current };
-    if (patch.maxConcurrent !== undefined) {
-        next.maxConcurrent = patch.maxConcurrent;
-    }
-    if (patch.credentialSource !== undefined) {
-        next.credentialSource = patch.credentialSource;
-    }
-    const out = {};
-    if (next.maxConcurrent !== undefined) {
-        out.maxConcurrent = next.maxConcurrent;
-    }
-    if (next.credentialSource !== undefined) {
-        out.credentialSource = next.credentialSource;
-    }
+    const next = applyFactorySettingsPatch(readFactorySettingsForContext(ctx), patch);
+    const out = serializeFactorySettings(next);
     ensureSettingsDirForContext(ctx);
     writeFileSync(settingsFilePathForContext(ctx), `${JSON.stringify(out, null, 2)}\n`, "utf8");
 }
 export function writeFactorySettings(cwd, patch) {
-    if (patch.credentialSource !== undefined &&
-        parseCredentialSource(patch.credentialSource) === undefined) {
-        throw new Error(INVALID_CREDENTIAL_SOURCE_MESSAGE);
-    }
-    if (patch.maxConcurrent !== undefined &&
-        parseSlotCount(patch.maxConcurrent) === undefined) {
-        throw new Error(INVALID_SLOT_COUNT_MESSAGE);
-    }
-    const current = readFactorySettings(cwd);
-    const next = { ...current };
-    if (patch.maxConcurrent !== undefined) {
-        next.maxConcurrent = patch.maxConcurrent;
-    }
-    if (patch.credentialSource !== undefined) {
-        next.credentialSource = patch.credentialSource;
-    }
-    const out = {};
-    if (next.maxConcurrent !== undefined) {
-        out.maxConcurrent = next.maxConcurrent;
-    }
-    if (next.credentialSource !== undefined) {
-        out.credentialSource = next.credentialSource;
-    }
+    const next = applyFactorySettingsPatch(readFactorySettings(cwd), patch);
+    const out = serializeFactorySettings(next);
     const root = path.resolve(cwd);
     mkdirSync(storeRootFor(root), { recursive: true });
     writeFileSync(settingsFilePath(cwd), `${JSON.stringify(out, null, 2)}\n`, "utf8");
@@ -158,17 +168,17 @@ export function writeMaxConcurrentToGlobal(maxConcurrent) {
         throw new Error(INVALID_SLOT_COUNT_MESSAGE);
     }
     const current = parseFactorySettingsFromRaw(readRawSettingsFromFile(globalSettingsFilePath()));
-    const next = { ...current, maxConcurrent };
-    const out = {};
-    if (next.maxConcurrent !== undefined) {
-        out.maxConcurrent = next.maxConcurrent;
-    }
-    if (next.credentialSource !== undefined) {
-        out.credentialSource = next.credentialSource;
-    }
+    const next = applyFactorySettingsPatch(current, { maxConcurrent });
+    const out = serializeFactorySettings(next);
     mkdirSync(path.dirname(globalSettingsFilePath()), { recursive: true });
     writeFileSync(globalSettingsFilePath(), `${JSON.stringify(out, null, 2)}\n`, "utf8");
 }
+export function readWorkshopModelFromFile(cwd) {
+    return readFactorySettings(cwd).workshopModel;
+}
+export function writeWorkshopModelToFile(cwd, workshopModel) {
+    writeFactorySettings(cwd, { workshopModel });
+}
 export function readCredentialSourceFromFile(cwd) {
     return readFactorySettings(cwd).credentialSource;
 }

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,4 +1,7 @@
 import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
+import { loginCheckPromptBlock, readStageLoginCheck, } from "../browser/loginCheck.js";
+import { humanLoginPromptBlock, isHumanLoginStage } from "../browser/humanLogin.js";
+import { BROWSER_SKILL_NAME, resolveBuiltinSkillFile, } from "../config/builtinSkills.js";
 import { resolveSkillByName, } from "../config/listSkills.js";
 import { loadHostConfig } from "../config/hostConfig.js";
 import { defaultSeededRoots } from "../config/seededCatalog.js";
@@ -7,6 +10,7 @@ import { mkdir } from "node:fs/promises";
 import { runSkillsDir } from "./runSkills.js";
 import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, mcpCatalogExists, mcpCatalogPath, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
 import { attemptArtifactsDir, attemptStreamLogPath } from "../runstore/workspaceLayout.js";
+import { redactBrowserActivityEvent, redactBrowserSecrets, } from "../agent/streamLogRedact.js";
 import { createStageStreamLogWriter, } from "./stageStreamLog.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
@@ -68,6 +72,17 @@ async function resolveStageSkillForRun(stage, catalog, options) {
         skillOrigin: resolved.origin,
     };
 }
+/** Browser stages get the `browser` skill (run > checkout > host > built-in). A missing skill is not an error. */
+async function resolveBrowserSkillFile(stage, catalog, options) {
+    if (stage.browser === undefined || stage.skill === BROWSER_SKILL_NAME) {
+        return undefined;
+    }
+    const resolved = await resolveStageSkillForRun({ skill: BROWSER_SKILL_NAME }, catalog, options);
+    if (resolved.ok && resolved.skillFilePath !== undefined) {
+        return resolved.skillFilePath;
+    }
+    return resolveBuiltinSkillFile(BROWSER_SKILL_NAME);
+}
 async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir, options) {
     const names = allowlist ?? [];
     if (names.length === 0)
@@ -151,6 +166,13 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
     });
     if (!skill.ok)
         return skill;
+    const browserSkillFilePath = await resolveBrowserSkillFile(input.stage, catalog, {
+        bindingKind: resolveOptions.bindingKind,
+        checkoutRoot: resolveOptions.checkoutRoot,
+        factoryCwd,
+        trustWorkspaceConfig: resolveOptions.trustWorkspaceConfig,
+        workspaceDir: resolveOptions.workspaceDir,
+    });
     let resolvedMcpServers;
     const origins = [];
     try {
@@ -207,16 +229,41 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
             })).catch(() => null);
         }
     }
+    let loginCheck;
+    const humanLogin = isHumanLoginStage(resolveOptions.dag, input.stage.id, input.stage.browser);
+    if (input.stage.browser?.check !== undefined && !humanLogin) {
+        loginCheck = await readStageLoginCheck(resolveOptions.workspaceDir, stageIdForManifest);
+        if (loginCheck === undefined) {
+            return { ok: false, reason: "browser login check result is missing" };
+        }
+    }
     try {
         const handle = agent.openStage({
             ...input,
             stage: {
                 ...input.stage,
-                system_prompt: stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir),
+                system_prompt: `${stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir)}${loginCheck !== undefined ? `\n\n${loginCheckPromptBlock(loginCheck)}` : ""}${humanLogin ? `\n\n${humanLoginPromptBlock(input.stage.browser?.login_url ?? input.stage.browser?.check?.url)}` : ""}`,
+                ...(loginCheck !== undefined
+                    ? {
+                        pre_emit_checks: [
+                            ...(input.stage.pre_emit_checks ?? []),
+                            {
+                                id: "browser_login_check",
+                                type: "browser_login_check",
+                                state: loginCheck.state,
+                                logged_in: loginCheck.logged_in,
+                                url: loginCheck.url,
+                            },
+                        ],
+                    }
+                    : {}),
             },
             ...(skill.skillFilePath !== undefined
                 ? { skillFilePath: skill.skillFilePath }
                 : {}),
+            ...(browserSkillFilePath !== undefined
+                ? { browserSkillFilePath }
+                : {}),
             ...(resolvedMcpServers !== undefined ? { resolvedMcpServers } : {}),
             onResolvedModel: async (info) => {
                 await patchRunManifest(resolveOptions.store, resolveOptions.runId, (m) => withStageResolvedModel(m, info.stageId, {
@@ -357,7 +404,10 @@ export async function openStageAttempt(input) {
         return priorInput;
     const roots = resolveAttemptRoots(input, stageId);
     const attempt = input.attemptCtx?.attempt ?? 1;
-    const streamWriter = (input.streamLogWriterFactory ?? createStageStreamLogWriter)(attemptStreamLogPath(input.workspaceDir, stageId, attempt));
+    const streamLogPath = attemptStreamLogPath(input.workspaceDir, stageId, attempt);
+    const streamWriter = input.streamLogWriterFactory
+        ? input.streamLogWriterFactory(streamLogPath)
+        : createStageStreamLogWriter(streamLogPath, input.stage.browser !== undefined ? { redact: redactBrowserSecrets } : {});
     const resumeToken = input.resumeToken ??
         resumeSessionFilePath(input.workspaceDir, stageId, attempt);
     const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
@@ -394,7 +444,9 @@ export async function openStageAttempt(input) {
         resumeToken,
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: (event) => {
-            input.onActivity?.(event);
+            input.onActivity?.(input.stage.browser !== undefined
+                ? redactBrowserActivityEvent(event)
+                : event);
             void streamWriter.flush();
         },
         onAssistantTextDelta: streamWriter.onDelta,

package/dist/runtime/stageEnvironment.js

@@ -25,6 +25,7 @@ export const STAGE_ENV_ALLOWLIST = [
     "https_proxy",
     "no_proxy",
     "STAGEFLOW_HOME",
+    "STAGEFLOW_CURSOR_EXTENSION",
 ];
 const PROVIDER_AND_CLOUD_NAMES = [
     "ANTHROPIC_API_KEY",

package/dist/runtime/stageHitl.d.ts

@@ -4,6 +4,7 @@ import { type StageAttemptContext } from "./stageAttemptContext.js";
 import { type AskOperatorPrompt } from "../tools/askOperator.js";
 export type DeliverAnswerResult = {
     ok: true;
+    verification?: "failed_retrying";
 } | {
     ok: false;
     reason: string;

package/dist/runtime/stageHitl.js

@@ -1,3 +1,4 @@
+import { parseHostGateContext } from "../browser/gateHandoff.js";
 import { appendOperatorAnswer, appendOperatorPrompt, derivePendingPrompt, } from "../hitl/qaTrail.js";
 import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
 import { attemptContext } from "./stageAttemptContext.js";
@@ -7,7 +8,10 @@ export function tryParsePendingPrompt(pendingRequest) {
         return undefined;
     }
     try {
-        return normalizePromptIds(parseAskOperatorParams(pendingRequest));
+        return {
+            ...normalizePromptIds(parseAskOperatorParams(pendingRequest)),
+            ...parseHostGateContext(pendingRequest),
+        };
     }
     catch {
         return undefined;

package/dist/runtime/stageProcessLauncher.d.ts

@@ -17,6 +17,8 @@ export type StageLaunchInput = {
     bindingKind?: DerivedBindingKind;
     grants?: ResolvedStageGrants;
     attemptHome?: string;
+    browserEnv?: Record<string, string>;
+    model?: string;
 };
 export type StageLaunchResult = {
     type: "succeeded";
@@ -45,6 +47,7 @@ export declare class StageProcessLauncher {
     private readonly env;
     private readonly explicitChildExtras;
     private readonly cliEntry;
+    private readonly workerExecArgv;
     private readonly logger;
     private readonly forkFn;
     private readonly active;

package/dist/runtime/stageProcessLauncher.js

@@ -1,7 +1,10 @@
 import * as childProcess from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { logger as rootLogger, resolveLogMaxLineBytes, } from "../logging/logger.js";
+import { isCursorModelRef, readCursorApiKey } from "../agent/cursorProvider.js";
+import { BROWSER_ENV_PREFIX } from "../browser/browserHost.js";
 import { PACKAGE_VERSION } from "../package-meta.js";
+import { PI_HOME_AUTH_PATH_ENV, stageflowAgentAuthPath } from "./credentialBinding.js";
 import { redactString } from "../logging/redact.js";
 import { getNamedSecrets } from "../logging/namedSecrets.js";
 import { readMaxActiveStageProcesses, } from "./stageConcurrency.js";
@@ -10,6 +13,28 @@ import { buildStageEnvironment, isAmbientBlockedEnv, isForeverDeniedSecret, } fr
 import { ensureStageCacheDirs } from "./stageCacheEnv.js";
 import { SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 import { overlayStageBindingEnv, } from "./stageRoots.js";
+function defaultStageCliEntry() {
+    const source = import.meta.url.split("?")[0]?.endsWith(".ts") === true;
+    return fileURLToPath(new URL(source ? "../cli.ts" : "../cli.js", import.meta.url));
+}
+function isTypeScriptEntry(entry) {
+    return /\.(?:m|c)?ts$/.test(entry);
+}
+/**
+ * A compiled `dist/cli.js` child is plain node. `npm run dev` is TypeScript,
+ * and this launcher sets execArgv explicitly so the parent's tsx loader is
+ * not inherited. Load that entry with the same tsx hooks the dev CLI uses.
+ */
+function tsxLoaderExecArgv() {
+    try {
+        const preflight = fileURLToPath(import.meta.resolve("tsx/preflight"));
+        const loader = import.meta.resolve("tsx");
+        return ["--require", preflight, "--import", loader];
+    }
+    catch {
+        return [];
+    }
+}
 function flushCappedPartial(log, event, text, maxLineBytes) {
     let remaining = redactString(text, { namedSecrets: getNamedSecrets() });
     while (Buffer.byteLength(remaining, "utf8") > maxLineBytes) {
@@ -109,6 +134,7 @@ export class StageProcessLauncher {
     env;
     explicitChildExtras;
     cliEntry;
+    workerExecArgv;
     logger;
     forkFn;
     active = new Map();
@@ -126,9 +152,11 @@ export class StageProcessLauncher {
                 : undefined;
         this.maxActive = readMaxActiveStageProcesses(this.env, options.maxActiveStageProcesses);
         this.heapMb = getContainerLimits().maxOldSpaceSizeMb;
-        this.cliEntry =
-            options.cliEntry ??
-                fileURLToPath(new URL("../cli.js", import.meta.url));
+        this.cliEntry = options.cliEntry ?? defaultStageCliEntry();
+        this.workerExecArgv = [
+            `--max-old-space-size=${this.heapMb}`,
+            ...(isTypeScriptEntry(this.cliEntry) ? tsxLoaderExecArgv() : []),
+        ];
         this.logger =
             options.logger ?? rootLogger.child({ component: "runtime" });
         this.forkFn = options.forkFn ?? childProcess.fork;
@@ -290,6 +318,7 @@ export class StageProcessLauncher {
             cacheVars: ensureStageCacheDirs(),
             grants: input.grants,
             attemptHome: input.attemptHome,
+            runVars: input.browserEnv,
             packageVersion: PACKAGE_VERSION,
         });
         for (const warning of built.warnings) {
@@ -301,14 +330,32 @@ export class StageProcessLauncher {
         const withExtras = this.explicitChildExtras !== undefined
             ? { ...built.env, ...this.explicitChildExtras }
             : built.env;
-        const childEnv = overlayStageBindingEnv(withExtras, input.env ?? {}, input.bindingKind ?? "unbound");
+        const overlaid = overlayStageBindingEnv(withExtras, input.env ?? {}, input.bindingKind ?? "unbound");
+        const withBrowser = input.browserEnv !== undefined
+            ? {
+                ...Object.fromEntries(Object.entries(overlaid).filter(([name]) => !name.startsWith(BROWSER_ENV_PREFIX))),
+                ...input.browserEnv,
+            }
+            : overlaid;
+        const childEnv = {
+            ...withBrowser,
+            [PI_HOME_AUTH_PATH_ENV]: stageflowAgentAuthPath(),
+        };
+        const cursorApiKey = readCursorApiKey(hostEnv);
+        if (isCursorModelRef(input.model ?? "") &&
+            cursorApiKey !== undefined &&
+            cursorApiKey !== "" &&
+            childEnv.CURSOR_API_KEY === undefined) {
+            childEnv.CURSOR_API_KEY = cursorApiKey;
+        }
         const child = this.forkFn(this.cliEntry, args, {
             cwd: input.rootDir,
             env: { ...childEnv, [SF_STAGE_WORKER]: "1" },
             stdio: ["pipe", "pipe", "pipe", "ipc"],
             detached: true,
             // Explicit: do not inherit Host execArgv; set heap from cgroup budget.
-            execArgv: [`--max-old-space-size=${this.heapMb}`],
+            // TypeScript entries also get the tsx loader, since that inheritance is off.
+            execArgv: this.workerExecArgv,
         });
         const key = activeKey(input.runId, input.stageId);
         const tracked = {

package/dist/runtime/stageRunner.d.ts

@@ -1,4 +1,6 @@
 import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunResult, StageSessionMode } from "../agent/port.js";
+import { type HostGateContext } from "../browser/gateHandoff.js";
+import type { StageBrowserSupport } from "../browser/browserHost.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { LoadedStageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
@@ -49,6 +51,8 @@ export type RunStageOptions = {
     feedbackLoopContext?: FeedbackLoopContext;
     resumeToken?: string;
     stageEnv?: Record<string, string>;
+    /** Test seam for the Host login check run by a `browser_login` verify item. */
+    browser?: Pick<StageBrowserSupport, "runner" | "loginCheck">;
 };
 /**
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).
@@ -62,5 +66,6 @@ export declare function runStageYieldLoop(options: {
     store?: RunStore;
     attemptCtx?: StageAttemptContext;
     skipGates?: boolean;
+    gateContext?: HostGateContext;
 }): Promise<RunStageYieldLoopResult>;
 export declare function runStage(options: RunStageOptions): Promise<RunStageOutcome>;

package/dist/runtime/stageRunner.js

@@ -1,8 +1,11 @@
+import { hostGateContextFor, stampGateRequest, } from "../browser/gateHandoff.js";
 import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
 import { buildStageRoots, withResolvedAuthPath, } from "./stageRoots.js";
 import { createDefaultHitlQaHooks, recordWaitEnter, } from "./stageHitl.js";
 import { openStageAttempt, } from "./stageAttemptBootstrap.js";
 import { createVerifiedStageExecution } from "./verifiedStageExecution.js";
+import { BROWSER_STAGE_PATTERNS, redact } from "../logging/redact.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
 import { isStageTimeoutReason } from "../agent/stageTimeout.js";
 export function isRunStageWaiting(outcome) {
     return "waiting" in outcome && outcome.waiting === true;
@@ -44,11 +47,16 @@ async function appendLifecycleEventAndPatchExecution(options) {
     }
 }
 async function finalizeStageResult(options) {
-    const { store, runId, stageId, result, activityChain, attemptCtx } = options;
+    const { store, runId, stageId, result, activityChain, attemptCtx, browser } = options;
     const attemptOpt = attemptCtx?.eventOptions();
     await activityChain;
     if (result.envelope) {
-        await store.writeEnvelope(runId, stageId, result.envelope, attemptOpt);
+        await store.writeEnvelope(runId, stageId, browser
+            ? redact(result.envelope, {
+                patterns: BROWSER_STAGE_PATTERNS,
+                namedSecrets: getNamedSecrets(),
+            })
+            : result.envelope, attemptOpt);
     }
     if (!result.ok) {
         await appendLifecycleEventAndPatchExecution({
@@ -75,10 +83,11 @@ async function finalizeStageResult(options) {
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).
  */
 export async function runStageYieldLoop(options) {
-    const { handle, runId, stageId, hitl, workerMode, store, attemptCtx, skipGates } = options;
+    const { handle, runId, stageId, hitl, workerMode, store, attemptCtx, skipGates, gateContext } = options;
     while (true) {
         const event = await handle.next();
         if (event.status === "waiting_for_input") {
+            const request = stampGateRequest(event.request, gateContext);
             if (skipGates) {
                 return {
                     ok: false,
@@ -96,7 +105,7 @@ export async function runStageYieldLoop(options) {
                     store,
                     runId,
                     stageId,
-                    request: event.request,
+                    request,
                     attemptCtx,
                     qaHooks: createDefaultHitlQaHooks(store),
                 });
@@ -108,14 +117,14 @@ export async function runStageYieldLoop(options) {
                     reason: "stage requested wait but no HITL controller is configured",
                 };
             }
-            await hitl.enterWait(runId, stageId, handle, event.request, attemptCtx);
+            await hitl.enterWait(runId, stageId, handle, request, attemptCtx);
             continue;
         }
         return event.result;
     }
 }
 export async function runStage(options) {
-    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, } = options;
+    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, browser: browserSeams, } = options;
     const stageId = options.stageId ?? stage.id;
     const attemptOpt = attemptCtx?.eventOptions();
     const baseRoots = rootsOverride ??
@@ -144,6 +153,19 @@ export async function runStage(options) {
         dag,
         roots,
         commandEnv: stageEnv ?? process.env,
+        ...(stage.browser?.check !== undefined
+            ? {
+                browserLogin: {
+                    check: stage.browser.check,
+                    ...(browserSeams?.runner !== undefined
+                        ? { runner: browserSeams.runner }
+                        : {}),
+                    ...(browserSeams?.loginCheck !== undefined
+                        ? { options: browserSeams.loginCheck }
+                        : {}),
+                },
+            }
+            : {}),
     });
     await verifiedExecution.prepare();
     console.error(`Running stage ${stageId} (${stage.model})...`);
@@ -209,6 +231,7 @@ export async function runStage(options) {
             store: workerMode ? store : undefined,
             attemptCtx,
             skipGates,
+            gateContext: hostGateContextFor(stage.browser),
         });
     }
     catch (err) {
@@ -253,6 +276,7 @@ export async function runStage(options) {
             result,
             activityChain,
             attemptCtx,
+            browser: stage.browser !== undefined,
         });
     }
     finally {

package/dist/runtime/stageStreamLog.d.ts

@@ -14,4 +14,5 @@ export type StageStreamLogWriter = {
 export declare function createStageStreamLogWriter(streamLogPath: string, options?: {
     flushThrottleMs?: number;
     capBytes?: number;
+    redact?: (text: string) => string;
 }): StageStreamLogWriter;

package/dist/runtime/stageStreamLog.js

@@ -54,6 +54,7 @@ async function appendChunk(streamLogPath, chunk, capBytes) {
 export function createStageStreamLogWriter(streamLogPath, options = {}) {
     const flushThrottleMs = options.flushThrottleMs ?? STREAM_FLUSH_THROTTLE_MS;
     const capBytes = options.capBytes ?? DEFAULT_CAP_BYTES;
+    const scrub = options.redact ?? redactSecrets;
     let buffer = "";
     let timer = null;
     // Serializes disk writes so the throttle timer and an eager flush() never race.
@@ -65,7 +66,7 @@ export function createStageStreamLogWriter(streamLogPath, options = {}) {
         }
         if (!buffer)
             return writeChain;
-        const chunk = redactSecrets(buffer);
+        const chunk = scrub(buffer);
         buffer = "";
         writeChain = writeChain.then(() => appendChunk(streamLogPath, chunk, capBytes));
         return writeChain;

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 {};