stageflow 0.32.0 → 0.35.0

package/dist/runstore/stageSnapshot.js

@@ -1,3 +1,4 @@
+import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { derivePendingPrompt } from "../hitl/qaTrail.js";
 import { stageStatusFromEvents } from "./port.js";
 import { listArtifactNames } from "./workspaceLayout.js";
@@ -19,6 +20,7 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
     let envelope;
     let attempt_count;
     let cost_usd;
+    let usage;
     if (latest !== null) {
         events = await store.listStageEvents(runId, stageId, latest.attempt);
         status = stageStatusFromEvents(events);
@@ -26,6 +28,7 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
         attempt_count = await store.countStageAttempts(runId, stageId);
         const executions = await store.listStageExecutions(runId, stageId);
         cost_usd = sumStageExecutionCost(executions);
+        usage = mergeStageExecutionUsage(executions);
     }
     else {
         events = await store.listStageEvents(runId, stageId);
@@ -46,8 +49,24 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
         attempt_count,
         ...(pending ? { pending_prompt: pending } : {}),
         ...(cost_usd !== undefined ? { cost_usd } : {}),
+        ...(usage !== undefined ? { usage } : {}),
     };
 }
+export function mergeStageExecutionUsage(executions) {
+    const usages = executions
+        .map((e) => e.usage)
+        .filter((u) => u !== undefined);
+    if (usages.length === 0)
+        return undefined;
+    const merged = emptyStageUsage();
+    for (const u of usages) {
+        for (const [model, breakdown] of Object.entries(u.models)) {
+            addModelUsage(merged, model, breakdown);
+        }
+    }
+    merged.costUsd = usages.reduce((sum, u) => sum + u.costUsd, 0);
+    return merged;
+}
 /** Sum cost across every attempt — retries are real spend too, so a stage's total isn't just its latest attempt. */
 function sumStageExecutionCost(executions) {
     const costs = executions.map((e) => e.cost_usd).filter((c) => c !== undefined);

package/dist/runstore/workspaceLayout.js

@@ -1,5 +1,8 @@
 import { access, lstat, mkdir, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
+import { globalCredentialRoot } from "../project/globalHome.js";
+import { STAGEFLOW_AGENT_AUTH_PATH_ENV } from "../runtime/credentialBinding.js";
+import { SF_STAGE_WORKER } from "../runtime/stageWorkerProtocol.js";
 export { stageDir } from "./paths.js";
 export function guardStageId(stageId) {
     if (stageId.includes("..") ||
@@ -101,6 +104,15 @@ export async function resolveEffectiveRealPath(candidatePath) {
         }
     }
 }
+function credentialRootForFileToolDenial() {
+    if (process.env[SF_STAGE_WORKER] === "1") {
+        const stamped = process.env[STAGEFLOW_AGENT_AUTH_PATH_ENV]?.trim();
+        if (!stamped)
+            return undefined;
+        return path.resolve(path.dirname(stamped), "..");
+    }
+    return globalCredentialRoot();
+}
 export async function durableRootFileToolDenial(candidatePath, runWorkspaceDir, durableRoot, allowlistedRoots) {
     const fileReal = await resolveEffectiveRealPath(candidatePath);
     if (fileReal === undefined) {
@@ -137,6 +149,21 @@ export async function durableRootFileToolDenial(candidatePath, runWorkspaceDir,
     if (isInsideDir(fileReal, durableReal)) {
         return STAGEFLOW_PATH_DENIED;
     }
+    const credentialRoot = credentialRootForFileToolDenial();
+    if (credentialRoot !== undefined) {
+        let credentialReal;
+        try {
+            credentialReal = await realpath(credentialRoot);
+        }
+        catch {
+            credentialReal = path.resolve(credentialRoot);
+        }
+        if (credentialReal !== durableReal &&
+            !isInsideDir(credentialReal, durableReal) &&
+            isInsideDir(fileReal, credentialReal)) {
+            return STAGEFLOW_PATH_DENIED;
+        }
+    }
     return undefined;
 }
 export function resolveArtifactTarget(runWorkspaceDir, stageId, attempt, relativePath) {

package/dist/runstore/writeContainedArtifact.d.ts

@@ -0,0 +1 @@
+export declare function writeContainedArtifact(runWorkspaceDir: string, artifactsDirectory: string, absolutePath: string, content: string): Promise<void>;

package/dist/runstore/writeContainedArtifact.js

@@ -0,0 +1,52 @@
+/**
+ * Atomic write of one file under a stage attempt's artifacts directory.
+ * Refuses symlinked or hard-linked targets and any path that resolves outside
+ * the artifacts directory.
+ */
+import { randomBytes } from "node:crypto";
+import { lstat, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureRealArtifactsDir, isInsideDir, resolveContainedParent, } from "./workspaceLayout.js";
+async function assertSafeWriteTarget(targetPath) {
+    try {
+        const st = await lstat(targetPath);
+        if (st.isSymbolicLink()) {
+            throw new Error("path escapes the stage artifacts directory");
+        }
+        if (st.nlink > 1) {
+            throw new Error("refusing to overwrite hard-linked file");
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+export async function writeContainedArtifact(runWorkspaceDir, artifactsDirectory, absolutePath, content) {
+    const { realArtifacts } = await ensureRealArtifactsDir(runWorkspaceDir, artifactsDirectory);
+    const relativeToArtifacts = path.relative(artifactsDirectory, absolutePath);
+    const parent = await resolveContainedParent(realArtifacts, relativeToArtifacts);
+    const baseName = path.basename(absolutePath);
+    const targetPath = path.join(parent, baseName);
+    await assertSafeWriteTarget(targetPath);
+    const tmpName = `.sf-artifact-${randomBytes(8).toString("hex")}.tmp`;
+    const tmpPath = path.join(parent, tmpName);
+    try {
+        await writeFile(tmpPath, content, "utf8");
+        await rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        try {
+            await unlink(tmpPath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        throw err;
+    }
+    const realWritten = await realpath(targetPath);
+    if (!isInsideDir(realWritten, realArtifacts)) {
+        throw new Error("path escapes the stage artifacts directory");
+    }
+}

package/dist/runtime/containerLimits.d.ts

@@ -1,4 +1,3 @@
-import os from "node:os";
 export type ContainerLimits = {
     memoryLimitBytes: number | undefined;
     maxActiveStageProcesses: number;
@@ -12,5 +11,3 @@ export declare function readContainerMemoryLimit(roots?: readonly string[]): {
 export declare function deriveContainerLimits(memoryLimitBytes: number | undefined, source?: ContainerLimits["source"]): ContainerLimits;
 export declare function getContainerLimits(): ContainerLimits;
 export declare function resetContainerLimitsForTests(): void;
-/** Test hook: prove sizing never consults os.totalmem. */
-export declare function assertNoOsTotalmemInSizing(): typeof os.totalmem;

package/dist/runtime/containerLimits.js

@@ -1,5 +1,4 @@
 import { readFileSync, existsSync } from "node:fs";
-import os from "node:os";
 const HOST_RESERVE_MIB = 512;
 const WORKER_BUDGET_MIB = 512;
 const MAX_CAP = 8;
@@ -78,7 +77,3 @@ export function getContainerLimits() {
 export function resetContainerLimitsForTests() {
     cached = undefined;
 }
-/** Test hook: prove sizing never consults os.totalmem. */
-export function assertNoOsTotalmemInSizing() {
-    return os.totalmem;
-}

package/dist/runtime/credentialBinding.d.ts

@@ -19,5 +19,8 @@ export declare function stageflowAgentAuthPath(override?: string): string;
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
 export declare function ensureSfOwnedAuthStore(): string;
+/** Use this auth file for credential binding and do not create the operator home. */
+export declare function runWithExplicitAuthPath<T>(authPath: string, fn: () => Promise<T>): Promise<T>;
+export declare function currentExplicitAuthPath(): string | undefined;
 export declare function resolveCredentialBinding(ctx: ProjectContext | string, _options?: ResolveCredentialBindingOptions): CredentialBinding;
 export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";

package/dist/runtime/credentialBinding.js

@@ -1,11 +1,12 @@
-import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
-import { ensureGlobalHome } from "../project/globalHome.js";
+import { ensureGlobalHome, globalCredentialRoot } from "../project/globalHome.js";
 import { resolveProjectContext, } from "../project/resolveProjectContext.js";
 import { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, } from "./settingsFile.js";
 export { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, };
 export function sfOwnedAgentDir() {
-    return path.join(ensureGlobalHome(), "agent");
+    return path.join(globalCredentialRoot(), "agent");
 }
 export function sfOwnedAuthPath() {
     return path.join(sfOwnedAgentDir(), "auth.json");
@@ -41,7 +42,15 @@ export function isUsableAuthFile(authPath) {
 }
 export function ensureSfOwnedAuthStore() {
     ensureGlobalHome();
-    const authPath = sfOwnedAuthPath();
+    const agentDir = sfOwnedAgentDir();
+    mkdirSync(agentDir, { recursive: true });
+    try {
+        chmodSync(agentDir, 0o700);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    const authPath = path.join(agentDir, "auth.json");
     if (!existsSync(authPath)) {
         writeFileSync(authPath, "{}\n", { encoding: "utf8", mode: 0o600 });
     }
@@ -53,13 +62,21 @@ export function ensureSfOwnedAuthStore() {
     }
     return authPath;
 }
+const explicitAuthPath = new AsyncLocalStorage();
+/** Use this auth file for credential binding and do not create the operator home. */
+export function runWithExplicitAuthPath(authPath, fn) {
+    return explicitAuthPath.run(path.resolve(authPath), fn);
+}
+export function currentExplicitAuthPath() {
+    return explicitAuthPath.getStore();
+}
 export function resolveCredentialBinding(ctx, _options = {}) {
+    const explicit = currentExplicitAuthPath();
     const projectCtx = typeof ctx === "string" ? resolveProjectContext(ctx) : ctx;
     const persisted = readCredentialSourceFromContext(projectCtx);
-    const authPath = ensureSfOwnedAuthStore();
     return {
         source: "sf_owned",
-        authPath,
+        authPath: explicit ?? sfOwnedAuthPath(),
         provisional: persisted === undefined,
     };
 }

package/dist/runtime/emailSource.js

@@ -1,10 +1,6 @@
-import path from "node:path";
 import { ImapFlow } from "imapflow";
-import { getCatalogScanPaths } from "../config/browseCatalog.js";
-import { loadTriggerOutcome } from "../config/loadTrigger.js";
-import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { listCatalogTriggerMatches, triggerStoreId, } from "../config/triggerCatalog.js";
 import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
-import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { matchesEventFilter } from "./triggerEventMatch.js";
 export const DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS = 1_000;
 export const DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS = 30_000;
@@ -122,20 +118,17 @@ export class EmailSource {
     }
     async start(onFire) {
         this.stopped = false;
-        const ctx = catalogContextFromStageflow(await resolveStageflowContext(this.cwd));
-        const scanPaths = await getCatalogScanPaths(ctx);
-        if (!scanPaths)
-            return;
-        const projectRoot = ctx.projectRoot ?? undefined;
-        const groups = await this.discover(scanPaths.triggerPaths);
+        const catalogTriggers = await listCatalogTriggerMatches({
+            store: this.store,
+            bootCwd: this.cwd,
+            sourceRootsOnly: true,
+        });
+        const groups = this.discover(catalogTriggers);
         for (const [mailboxKey, group] of groups) {
             for (const match of group.matches) {
-                const definitionRef = projectRoot !== undefined
-                    ? path.relative(projectRoot, match.path).replace(/\\/g, "/")
-                    : match.path;
                 await this.store.upsertTrigger({
-                    id: match.definition.id,
-                    definitionRef,
+                    id: triggerStoreId(match.project_root, match.definition.id),
+                    definitionRef: match.definition_ref,
                     enabled: true,
                 });
             }
@@ -161,13 +154,10 @@ export class EmailSource {
         }
         this.connections.clear();
     }
-    async discover(triggerPaths) {
+    discover(catalogTriggers) {
         const groups = new Map();
-        for (const triggerPath of triggerPaths) {
-            const outcome = await loadTriggerOutcome(triggerPath);
-            if (!outcome.ok)
-                continue;
-            const definition = outcome.value;
+        for (const match of catalogTriggers) {
+            const definition = match.definition;
             if (definition.kind !== "event" || !definition.enabled)
                 continue;
             const source = definition.event?.source;
@@ -181,7 +171,7 @@ export class EmailSource {
             }
             const mailboxKey = mailboxKeyFor(config);
             const group = groups.get(mailboxKey) ?? { config, matches: [] };
-            group.matches.push({ path: triggerPath, definition });
+            group.matches.push(match);
             groups.set(mailboxKey, group);
         }
         return groups;
@@ -274,20 +264,22 @@ export class EmailSource {
                 date: message.date,
                 text: message.text,
             };
-            for (const { definition } of conn.group.matches) {
+            for (const match of conn.group.matches) {
+                const { definition } = match;
                 if (!matchesEventFilter(definition.event?.match, summary))
                     continue;
-                await this.fireSafely(conn.onFire, definition, message, summary);
+                await this.fireSafely(conn.onFire, match, message, summary);
             }
         }
         if (maxUid > sinceUid) {
             await this.store.setTriggerAdapterState(mailboxKey, "uid", String(maxUid));
         }
     }
-    async fireSafely(onFire, definition, message, summary) {
+    async fireSafely(onFire, match, message, summary) {
+        const definition = match.definition;
         try {
             if (definition.task !== undefined) {
-                await onFire({ triggerId: definition.id });
+                await onFire({ triggerId: definition.id, project_root: match.project_root });
                 return;
             }
             const task = {
@@ -295,7 +287,7 @@ export class EmailSource {
                 goal: `Handle email: ${message.subject}`,
                 input: summary,
             };
-            await onFire({ triggerId: definition.id, task });
+            await onFire({ triggerId: definition.id, project_root: match.project_root, task });
         }
         catch (err) {
             this.logError(`email: firing trigger "${definition.id}" failed: ${errMsg(err)}`);

package/dist/runtime/githubPollSource.js

@@ -1,10 +1,6 @@
-import path from "node:path";
 import { Octokit } from "octokit";
-import { getCatalogScanPaths } from "../config/browseCatalog.js";
-import { loadTriggerOutcome } from "../config/loadTrigger.js";
-import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { listCatalogTriggerMatches, triggerStoreId, } from "../config/triggerCatalog.js";
 import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
-import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { matchesEventFilter } from "./triggerEventMatch.js";
 export const DEFAULT_GITHUB_POLL_INTERVAL_MS = 60_000;
 export const DEFAULT_GITHUB_TOKEN_SECRET = "GITHUB_TOKEN";
@@ -166,33 +162,27 @@ export class GithubPollSource {
      * instead of waiting on real interval timers.
      */
     async tick(onFire) {
-        const ctx = catalogContextFromStageflow(await resolveStageflowContext(this.cwd));
-        const scanPaths = await getCatalogScanPaths(ctx);
-        if (!scanPaths)
-            return;
-        const projectRoot = ctx.projectRoot ?? undefined;
-        const groups = await this.discover(scanPaths.triggerPaths);
+        const catalogTriggers = await listCatalogTriggerMatches({
+            store: this.store,
+            bootCwd: this.cwd,
+            sourceRootsOnly: true,
+        });
+        const groups = this.discover(catalogTriggers);
         for (const [repo, matches] of groups) {
             for (const match of matches) {
-                const definitionRef = projectRoot !== undefined
-                    ? path.relative(projectRoot, match.path).replace(/\\/g, "/")
-                    : match.path;
                 await this.store.upsertTrigger({
-                    id: match.definition.id,
-                    definitionRef,
+                    id: triggerStoreId(match.project_root, match.definition.id),
+                    definitionRef: match.definition_ref,
                     enabled: true,
                 });
             }
             await this.pollRepo(repo, matches, onFire);
         }
     }
-    async discover(triggerPaths) {
+    discover(catalogTriggers) {
         const groups = new Map();
-        for (const triggerPath of triggerPaths) {
-            const outcome = await loadTriggerOutcome(triggerPath);
-            if (!outcome.ok)
-                continue;
-            const definition = outcome.value;
+        for (const match of catalogTriggers) {
+            const definition = match.definition;
             if (definition.kind !== "event" || !definition.enabled)
                 continue;
             const source = definition.event?.source;
@@ -205,7 +195,7 @@ export class GithubPollSource {
                 continue;
             }
             const list = groups.get(repo) ?? [];
-            list.push({ path: triggerPath, definition });
+            list.push(match);
             groups.set(repo, list);
         }
         return groups;
@@ -256,18 +246,20 @@ export class GithubPollSource {
         const newItems = response.items.filter((item) => isNewerThanCursor(item, cursor)).reverse();
         for (const item of newItems) {
             const summary = normalizeGithubItem(item, repo);
-            for (const { definition } of matches) {
+            for (const match of matches) {
+                const { definition } = match;
                 if (!matchesEventFilter(definition.event?.match, summary))
                     continue;
-                await this.fireSafely(onFire, definition, summary);
+                await this.fireSafely(onFire, match, summary);
             }
         }
         await this.store.setTriggerAdapterState(adapterId, "cursor", JSON.stringify({ updatedAt: newest.updated_at, number: newest.number }));
     }
-    async fireSafely(onFire, definition, summary) {
+    async fireSafely(onFire, match, summary) {
+        const definition = match.definition;
         try {
             if (definition.task !== undefined) {
-                await onFire({ triggerId: definition.id });
+                await onFire({ triggerId: definition.id, project_root: match.project_root });
                 return;
             }
             const task = {
@@ -275,7 +267,7 @@ export class GithubPollSource {
                 goal: `Handle PR #${summary.number}: ${summary.title}`,
                 input: summary,
             };
-            await onFire({ triggerId: definition.id, task });
+            await onFire({ triggerId: definition.id, project_root: match.project_root, task });
         }
         catch (err) {
             this.logError(`github poll: firing trigger "${definition.id}" failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/runtime/pipelineRunner.d.ts

@@ -1,5 +1,5 @@
 import type { RunSubmission } from "../runstore/submission.js";
-import type { AgentPort } from "../agent/port.js";
+import type { StagePort } from "../agent/port.js";
 import { type ValidationFinding } from "../config/validateCatalog.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
@@ -54,7 +54,7 @@ export type PreparedPipeline = {
         workspaceDir: string;
         created?: boolean;
     };
-    agent: AgentPort;
+    agent: StagePort;
     store: RunStore;
     cwd: string;
     projectRoot: string;
@@ -81,7 +81,7 @@ export type ExecuteStagesOptions = {
 };
 export declare function executeStages(prepared: PreparedPipeline, options?: ExecuteStagesOptions): Promise<PipelineRunResult>;
 export declare function runPipeline(options: {
-    agent: AgentPort;
+    agent: StagePort;
     store: RunStore;
     taskPath?: string;
     taskYaml?: string;
@@ -101,7 +101,7 @@ export declare function runPipeline(options: {
 export declare function startPipeline(options: {
     dispatchKey?: string;
     submission?: RunSubmission;
-    agent: AgentPort;
+    agent: StagePort;
     store: RunStore;
     taskPath?: string;
     taskYaml?: string;

package/dist/runtime/pipelineScheduler.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPort } from "../agent/port.js";
+import type { StagePort } from "../agent/port.js";
 import type { RunPipelineDagSnapshot, RunStore, StageSnapshot } from "../runstore/port.js";
 import type { StageBrowserSupport } from "../browser/browserHost.js";
 import type { StageEnvelope } from "../types/envelope.js";
@@ -17,7 +17,7 @@ type SchedulerPreparedPipeline = {
         runId: string;
         workspaceDir: string;
     };
-    agent: AgentPort;
+    agent: StagePort;
     store: RunStore;
     cwd: string;
     projectRoot?: string;

package/dist/runtime/pipelineScheduler.js

@@ -2,6 +2,7 @@ import { normalizeForkChoice } from "../envelope/forkChoice.js";
 import { refreshRunDiskUsage } from "../runstore/diskUsage.js";
 import { buildPipelineDagSnapshotFromLoaded } from "../runstore/pipelineDagSnapshot.js";
 import { defaultStageBrowserSupport, resolveStageBrowserEnv, } from "../browser/stageBrowserEnv.js";
+import { runOwnerScope } from "../browser/ownerScope.js";
 import { teardownRunBrowsers, teardownStageBrowser, } from "../browser/browserTeardown.js";
 import { isHumanLoginStage } from "../browser/humanLogin.js";
 import { createRunLiveness } from "../browser/runLiveness.js";
@@ -856,6 +857,7 @@ export async function runPipelineDag(options) {
             let acquired;
             try {
                 acquired = await acquireStageProfile(prepared.browser ?? defaultStageBrowserSupport(), {
+                    scope: runOwnerScope(prepared.browser ?? defaultStageBrowserSupport(), { runId: run.runId }),
                     profile,
                     owner: { runId: run.runId, stageId },
                     isRunLive: createRunLiveness(store),
@@ -944,6 +946,7 @@ export async function runPipelineDag(options) {
             browserEnv = await resolveStageBrowserEnv(prepared.browser ?? defaultStageBrowserSupport(), {
                 runId: run.runId,
                 stageId,
+                scope: runOwnerScope(prepared.browser ?? defaultStageBrowserSupport(), { runId: run.runId }),
                 runDir: run.workspaceDir,
                 browser: stage.browser,
                 attempt,

package/dist/runtime/resumeReconstruct.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPort, OpaqueAnswer } from "../agent/port.js";
+import type { StagePort, OpaqueAnswer } from "../agent/port.js";
 import type { RunStore, RunMeta } from "../runstore/port.js";
 import type { LoadedPipeline } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
@@ -10,7 +10,7 @@ export type PreparedResumeContext = {
     runId: string;
     stageId: string;
     opaqueAnswer: OpaqueAnswer;
-    agent: AgentPort;
+    agent: StagePort;
     store: RunStore;
     hitl: StageHitlController;
     executionMode: StageExecutionMode;

package/dist/runtime/resumeTimedOut.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPort } from "../agent/port.js";
+import type { StagePort } from "../agent/port.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageExecutionMode } from "./stageConcurrency.js";
 import type { StageProcessLauncher } from "./stageProcessLauncher.js";
@@ -7,7 +7,7 @@ import { type OperatorCatalog } from "./stageAttemptBootstrap.js";
 export type ResumeTimedOutContext = {
     runId: string;
     stageId: string;
-    agent: AgentPort;
+    agent: StagePort;
     store: RunStore;
     hitl: StageHitlController;
     executionMode: StageExecutionMode;

package/dist/runtime/runManager.d.ts

@@ -1,5 +1,5 @@
 import { type RunSubmission } from "../runstore/submission.js";
-import type { AgentPort, OpaqueAnswer } from "../agent/port.js";
+import type { StagePort, OpaqueAnswer } from "../agent/port.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type DiskBreakdown, type FreeSpaceReader } from "../runstore/diskUsage.js";
 import { type RunStore } from "../runstore/port.js";
@@ -155,6 +155,9 @@ export declare class RunManager {
     private readonly queuedDone;
     private admissionDrainInFlight;
     private readonly resumeInFlight;
+    private readonly gateClosedListeners;
+    private readonly beforeBrowserTeardownListeners;
+    private readonly shutdownListeners;
     private readonly retryInFlight;
     private readonly retryStartOwner;
     private readonly retryStartWaiters;
@@ -176,7 +179,7 @@ export declare class RunManager {
     private readonly isGitProject;
     private acceptingWork;
     constructor(options: {
-        agent: AgentPort;
+        agent: StagePort;
         store: RunStore;
         cwd?: string;
         projectRoot?: string;
@@ -239,6 +242,7 @@ export declare class RunManager {
     hasActiveWorker(runId: string, stageId: string): boolean;
     sweepBrowserSessions(): Promise<{
         closed: string[];
+        released: string[];
     }>;
     reconcileOrphanedStages(): Promise<{
         reconciled: Array<{
@@ -267,6 +271,18 @@ export declare class RunManager {
     }>>;
     /** Rebuild in-memory admission queue from persisted `queued` rows (R27). */
     reenqueuePersistedQueuedRuns(): Promise<void>;
+    /** Called when a stage's gate stops accepting operator input (answered, abandoned) or a run is cancelled (no stage id). */
+    onGateClosed(listener: (runId: string, stageId?: string) => void): () => void;
+    /** Awaited (bounded by the browser support) before a stage's or run's browser is torn down; stageId absent means the whole run. */
+    beforeBrowserTeardown(listener: (input: {
+        runId: string;
+        stageId?: string;
+    }) => Promise<void> | void): () => void;
+    /** Called once the Host stops accepting work (drain start). */
+    onShutdown(listener: () => void): () => void;
+    private browserSupport;
+    private browserOption;
+    private notifyGateClosed;
     abandonStage(runId: string, stageId: string): Promise<AbandonStageResult>;
     cancelRun(runId: string, reason: string): Promise<CancelRunResult>;
     setA2aStore(store: A2aStore): void;