stageflow 0.27.0 → 0.31.0

package/dist/workshop/modelSettings.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_WORKSHOP_MODEL = "cursor/auto";
+export type ResolveWorkshopModelInput = {
+    sessionOverride?: string | null;
+    settingsDefault?: string | null;
+    profileDefault?: string | null;
+};
+/**
+ * Effective Workshop chat model: session override → Settings default → profile fallback.
+ * Credentials stay on the shared Stageflow provider auth stack; this only picks a model id.
+ */
+export declare function resolveWorkshopModel(input?: ResolveWorkshopModelInput): string;
+export declare function parseWorkshopModel(value: unknown): string | undefined;
+/**
+ * Model selected when Workshop chat opens.
+ * stageflow.yaml `model` wins; a saved Settings workshop model is used only
+ * when the manifest has none.
+ */
+export declare function readWorkshopOpenModel(cwd: string): Promise<string>;

package/dist/workshop/modelSettings.js

@@ -0,0 +1,44 @@
+import { globalModelFromManifest } from "../config/resolveModel.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { readFactorySettings } from "../runtime/settingsFile.js";
+export const DEFAULT_WORKSHOP_MODEL = "cursor/auto";
+/**
+ * Effective Workshop chat model: session override → Settings default → profile fallback.
+ * Credentials stay on the shared Stageflow provider auth stack; this only picks a model id.
+ */
+export function resolveWorkshopModel(input = {}) {
+    const session = normalizeModelId(input.sessionOverride);
+    if (session)
+        return session;
+    const settings = normalizeModelId(input.settingsDefault);
+    if (settings)
+        return settings;
+    const profile = normalizeModelId(input.profileDefault);
+    if (profile)
+        return profile;
+    return DEFAULT_WORKSHOP_MODEL;
+}
+export function parseWorkshopModel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Model selected when Workshop chat opens.
+ * stageflow.yaml `model` wins; a saved Settings workshop model is used only
+ * when the manifest has none.
+ */
+export async function readWorkshopOpenModel(cwd) {
+    const ctx = await resolveStageflowContext(cwd);
+    return resolveWorkshopModel({
+        settingsDefault: globalModelFromManifest(ctx.manifest) ??
+            readFactorySettings(cwd).workshopModel,
+    });
+}
+function normalizeModelId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/dist/workshop/sessionStore.d.ts

@@ -0,0 +1,61 @@
+export declare const WORKSHOP_SESSION_TITLE_MAX_LENGTH = 80;
+export type WorkshopSessionMessageRole = "assistant" | "user" | "system";
+export type WorkshopSessionMessage = {
+    id: string;
+    role: WorkshopSessionMessageRole;
+    text: string;
+    createdAt: string;
+};
+export type WorkshopSessionRecord = {
+    version: 1;
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    transcript: WorkshopSessionMessage[];
+    piSessionId: string | null;
+    activeBuildId?: string;
+};
+export type WorkshopSessionSummary = {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    activeBuildId?: string;
+};
+export type WorkshopSessionAppendMessage = {
+    id?: string;
+    role: WorkshopSessionMessageRole;
+    text: string;
+    createdAt?: string;
+};
+export type WorkshopSessionStoreErrorCode = "workshop_session_not_found";
+export declare class WorkshopSessionStoreError extends Error {
+    readonly code: WorkshopSessionStoreErrorCode;
+    readonly sessionId?: string;
+    constructor(message: string, code: WorkshopSessionStoreErrorCode, sessionId?: string);
+}
+export declare function resolveWorkshopSessionStoreRoot(): string;
+export declare function workshopSessionsDir(storeRoot: string): string;
+export declare function workshopSessionDir(storeRoot: string, sessionId: string): string;
+export declare function workshopSessionFilePath(storeRoot: string, sessionId: string): string;
+export declare function workshopSessionPiFilePath(storeRoot: string, sessionId: string): string;
+export declare function truncateWorkshopSessionTitle(text: string): string;
+export declare function parseWorkshopSessionRecord(value: unknown): WorkshopSessionRecord | null;
+export declare function readWorkshopSession(storeRoot: string, sessionId: string): WorkshopSessionRecord | null;
+export declare function createWorkshopSession(storeRoot: string, options?: {
+    id?: string;
+    now?: Date;
+    piSessionId?: string | null;
+}): WorkshopSessionRecord;
+export declare function getWorkshopSession(storeRoot: string, sessionId: string): WorkshopSessionRecord;
+export declare function listWorkshopSessions(storeRoot: string): WorkshopSessionSummary[];
+export declare function appendWorkshopSessionMessages(storeRoot: string, sessionId: string, messages: readonly WorkshopSessionAppendMessage[], options?: {
+    now?: Date;
+}): WorkshopSessionRecord;
+export declare function updateWorkshopSessionPiSessionId(storeRoot: string, sessionId: string, piSessionId: string | null, options?: {
+    now?: Date;
+}): WorkshopSessionRecord;
+export declare function updateWorkshopSessionActiveBuildId(storeRoot: string, sessionId: string, activeBuildId: string | null, options?: {
+    now?: Date;
+}): WorkshopSessionRecord;

package/dist/workshop/sessionStore.js

@@ -0,0 +1,254 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+export const WORKSHOP_SESSION_TITLE_MAX_LENGTH = 80;
+export class WorkshopSessionStoreError extends Error {
+    code;
+    sessionId;
+    constructor(message, code, sessionId) {
+        super(message);
+        this.name = "WorkshopSessionStoreError";
+        this.code = code;
+        if (sessionId !== undefined)
+            this.sessionId = sessionId;
+    }
+}
+export function resolveWorkshopSessionStoreRoot() {
+    return globalStageflowHome();
+}
+export function workshopSessionsDir(storeRoot) {
+    return path.join(storeRoot, "workshop", "sessions");
+}
+export function workshopSessionDir(storeRoot, sessionId) {
+    return path.join(workshopSessionsDir(storeRoot), guardSessionId(sessionId));
+}
+export function workshopSessionFilePath(storeRoot, sessionId) {
+    return path.join(workshopSessionDir(storeRoot, sessionId), "session.json");
+}
+export function workshopSessionPiFilePath(storeRoot, sessionId) {
+    return path.join(workshopSessionDir(storeRoot, sessionId), "pi-session.jsonl");
+}
+function guardSessionId(sessionId) {
+    const trimmed = sessionId.trim();
+    if (!trimmed ||
+        trimmed.includes("/") ||
+        trimmed.includes("\\") ||
+        trimmed.includes("..") ||
+        trimmed === ".") {
+        throw new Error(`invalid workshop session id: ${sessionId}`);
+    }
+    return trimmed;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function truncateWorkshopSessionTitle(text) {
+    const collapsed = text.trim().replace(/\s+/g, " ");
+    if (collapsed.length <= WORKSHOP_SESSION_TITLE_MAX_LENGTH)
+        return collapsed;
+    return collapsed.slice(0, WORKSHOP_SESSION_TITLE_MAX_LENGTH).trimEnd();
+}
+function parseMessage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (typeof value.id !== "string" || !value.id)
+        return null;
+    if (value.role !== "assistant" &&
+        value.role !== "user" &&
+        value.role !== "system") {
+        return null;
+    }
+    if (typeof value.text !== "string")
+        return null;
+    if (typeof value.createdAt !== "string" || !value.createdAt)
+        return null;
+    return {
+        id: value.id,
+        role: value.role,
+        text: value.text,
+        createdAt: value.createdAt,
+    };
+}
+export function parseWorkshopSessionRecord(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.version !== 1)
+        return null;
+    if (typeof value.id !== "string" || !value.id)
+        return null;
+    if (typeof value.title !== "string")
+        return null;
+    if (typeof value.createdAt !== "string" || !value.createdAt)
+        return null;
+    if (typeof value.updatedAt !== "string" || !value.updatedAt)
+        return null;
+    if (!Array.isArray(value.transcript))
+        return null;
+    if (value.piSessionId !== null && typeof value.piSessionId !== "string") {
+        return null;
+    }
+    if (value.activeBuildId !== undefined &&
+        value.activeBuildId !== null &&
+        typeof value.activeBuildId !== "string") {
+        return null;
+    }
+    const transcript = [];
+    for (const entry of value.transcript) {
+        const msg = parseMessage(entry);
+        if (!msg)
+            return null;
+        transcript.push(msg);
+    }
+    const activeBuildId = typeof value.activeBuildId === "string" ? value.activeBuildId.trim() : "";
+    return {
+        version: 1,
+        id: value.id,
+        title: value.title,
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        transcript,
+        piSessionId: value.piSessionId,
+        ...(activeBuildId ? { activeBuildId } : {}),
+    };
+}
+function writeSession(storeRoot, record) {
+    const dir = workshopSessionDir(storeRoot, record.id);
+    mkdirSync(dir, { recursive: true });
+    const payload = {
+        version: 1,
+        id: record.id,
+        title: record.title,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        transcript: record.transcript,
+        piSessionId: record.piSessionId,
+        ...(record.activeBuildId ? { activeBuildId: record.activeBuildId } : {}),
+    };
+    writeFileSync(workshopSessionFilePath(storeRoot, record.id), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+export function readWorkshopSession(storeRoot, sessionId) {
+    let id;
+    try {
+        id = guardSessionId(sessionId);
+    }
+    catch {
+        return null;
+    }
+    const filePath = workshopSessionFilePath(storeRoot, id);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const parsed = parseWorkshopSessionRecord(raw);
+        if (!parsed || parsed.id !== id)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function createWorkshopSession(storeRoot, options) {
+    const id = options?.id?.trim() || randomUUID();
+    guardSessionId(id);
+    if (readWorkshopSession(storeRoot, id)) {
+        throw new Error(`workshop session already exists: ${id}`);
+    }
+    const now = (options?.now ?? new Date()).toISOString();
+    const record = {
+        version: 1,
+        id,
+        title: "",
+        createdAt: now,
+        updatedAt: now,
+        transcript: [],
+        piSessionId: options?.piSessionId ?? null,
+    };
+    writeSession(storeRoot, record);
+    return record;
+}
+export function getWorkshopSession(storeRoot, sessionId) {
+    const record = readWorkshopSession(storeRoot, sessionId);
+    if (!record) {
+        throw new WorkshopSessionStoreError(`workshop_session_not_found: ${sessionId}`, "workshop_session_not_found", sessionId);
+    }
+    return record;
+}
+export function listWorkshopSessions(storeRoot) {
+    const dir = workshopSessionsDir(storeRoot);
+    if (!existsSync(dir))
+        return [];
+    const summaries = [];
+    for (const name of readdirSync(dir)) {
+        const record = readWorkshopSession(storeRoot, name);
+        if (!record)
+            continue;
+        summaries.push({
+            id: record.id,
+            title: record.title,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            ...(record.activeBuildId ? { activeBuildId: record.activeBuildId } : {}),
+        });
+    }
+    summaries.sort((a, b) => {
+        if (a.updatedAt !== b.updatedAt) {
+            return a.updatedAt < b.updatedAt ? 1 : -1;
+        }
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    return summaries;
+}
+export function appendWorkshopSessionMessages(storeRoot, sessionId, messages, options) {
+    const record = getWorkshopSession(storeRoot, sessionId);
+    const now = (options?.now ?? new Date()).toISOString();
+    let title = record.title;
+    const appended = [];
+    for (const msg of messages) {
+        const entry = {
+            id: msg.id?.trim() || randomUUID(),
+            role: msg.role,
+            text: msg.text,
+            createdAt: msg.createdAt || now,
+        };
+        appended.push(entry);
+        if (!title && entry.role === "user" && entry.text.trim()) {
+            title = truncateWorkshopSessionTitle(entry.text);
+        }
+    }
+    const next = {
+        ...record,
+        title,
+        updatedAt: now,
+        transcript: [...record.transcript, ...appended],
+    };
+    writeSession(storeRoot, next);
+    return next;
+}
+export function updateWorkshopSessionPiSessionId(storeRoot, sessionId, piSessionId, options) {
+    const record = getWorkshopSession(storeRoot, sessionId);
+    const next = {
+        ...record,
+        piSessionId,
+        updatedAt: (options?.now ?? new Date()).toISOString(),
+    };
+    writeSession(storeRoot, next);
+    return next;
+}
+export function updateWorkshopSessionActiveBuildId(storeRoot, sessionId, activeBuildId, options) {
+    const record = getWorkshopSession(storeRoot, sessionId);
+    const trimmed = activeBuildId?.trim() ?? "";
+    const next = {
+        ...record,
+        updatedAt: (options?.now ?? new Date()).toISOString(),
+    };
+    if (trimmed) {
+        next.activeBuildId = trimmed;
+    }
+    else {
+        delete next.activeBuildId;
+    }
+    writeSession(storeRoot, next);
+    return next;
+}

package/dist/workshop/workshopPin.d.ts

@@ -0,0 +1,72 @@
+import type { DraftPackage } from "../config/draftPackage.js";
+import type { OperatorAgentToolResult, WorkshopDraftContext } from "../operatorAgent/types.js";
+import { type WorkshopBuildRecord } from "./buildStore.js";
+export declare const WORKSHOP_UNLINKED_DRAFT_TOOL_ERROR = "No build is selected \u2014 draft tools cannot edit or save until a build is focused.";
+export type WorkshopPointerChange = {
+    buildId: string;
+    draft: DraftPackage;
+};
+export type WorkshopPinRegistry = {
+    get(sessionId: string): {
+        getContext(): unknown;
+        setContext(next: unknown): void;
+    } | undefined;
+    getPinnedBuildId(sessionId: string): string | null;
+    setPinnedBuildId(sessionId: string, buildId: string | null): void;
+    getLiveTurn(sessionId: string): {
+        onPointerChange?: (frame: WorkshopPointerChange) => void;
+    } | undefined;
+};
+export declare function enqueueSessionWrite<T>(sessionId: string, fn: () => T): Promise<T>;
+export declare function registerLiveWorkshopSession(sessionId: string, live: {
+    storeRoot: string;
+    registry: WorkshopPinRegistry;
+}): void;
+export declare function unregisterLiveWorkshopSession(sessionId: string): void;
+export declare function resetWorkshopPinStateForTests(): void;
+export declare function bindPinnedBuildContext(current: unknown, build: WorkshopBuildRecord, sessionId: string): WorkshopDraftContext;
+export declare function resolveLiveWorkshopBinding(context: unknown): {
+    sessionId: string;
+    registry: WorkshopPinRegistry;
+    storeRoot: string;
+} | null;
+/**
+ * Draft tools call this. Outside a workshop chat turn it does nothing.
+ * An unlinked chat turn fails the tool and does not create a build.
+ */
+export declare function rejectUnlinkedWorkshopDraftTool(context: unknown, toolName: string): OperatorAgentToolResult | null;
+/** Tied builds save to the stored path. Untitled builds keep the caller's destination. */
+export declare function resolvePinnedSaveDestination(context: unknown): {
+    directory: string;
+    pipelineFilename: string;
+} | null;
+/** A successful save of an untitled build records the operator destination on that id. */
+export declare function recordPinnedWorkshopSave(context: unknown, saved: {
+    directory: string;
+    pipelineFilename?: string;
+    projectRoot: string;
+    draft: DraftPackage;
+}): void;
+/**
+ * Create an untitled build and move this turn's pin onto it.
+ * Later edits in the turn persist on that id.
+ */
+export declare function pinWorkshopBuildOnCreate(input: {
+    sessionId: string;
+    draft: DraftPackage;
+    registry: WorkshopPinRegistry;
+    storeRoot: string;
+}): WorkshopBuildRecord;
+/**
+ * Focus a build. When this turn already has a pin, update the pointer only.
+ * When the turn started with none, move the pin and the host onto that build.
+ */
+export declare function focusWorkshopBuildPointer(input: {
+    sessionId: string;
+    buildId: string;
+    registry: WorkshopPinRegistry;
+    storeRoot: string;
+}): {
+    pinMoved: boolean;
+    activeBuildId: string;
+};

package/dist/workshop/workshopPin.js

@@ -0,0 +1,193 @@
+import path from "node:path";
+import { isWorkshopDraftContext } from "../operatorAgent/draftContext.js";
+import { createWorkshopBuild, getWorkshopBuild, readWorkshopBuild, updateWorkshopBuild, } from "./buildStore.js";
+import { updateWorkshopSessionActiveBuildId } from "./sessionStore.js";
+export const WORKSHOP_UNLINKED_DRAFT_TOOL_ERROR = "No build is selected — draft tools cannot edit or save until a build is focused.";
+const WORKSHOP_DRAFT_TOOL_NAMES = new Set([
+    "read_draft",
+    "validate_draft",
+    "create_pipeline",
+    "edit_pipeline",
+    "create_stage",
+    "edit_stage",
+    "create_task",
+    "edit_task",
+    "save",
+    "propose_draft",
+]);
+const sessionWriteTails = new Map();
+const liveBySession = new Map();
+export function enqueueSessionWrite(sessionId, fn) {
+    const prev = sessionWriteTails.get(sessionId) ?? Promise.resolve();
+    const run = prev.then(fn, fn);
+    sessionWriteTails.set(sessionId, run.then(() => undefined, () => undefined));
+    return run;
+}
+export function registerLiveWorkshopSession(sessionId, live) {
+    liveBySession.set(sessionId, live);
+}
+export function unregisterLiveWorkshopSession(sessionId) {
+    liveBySession.delete(sessionId);
+}
+export function resetWorkshopPinStateForTests() {
+    sessionWriteTails.clear();
+    liveBySession.clear();
+}
+function destinationFromRelativePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    const pipelineFilename = path.posix.basename(normalized);
+    const dir = path.posix.dirname(normalized);
+    return {
+        directory: dir === "." ? "." : dir,
+        pipelineFilename,
+    };
+}
+function relativePathFromDestination(directory, pipelineFilename) {
+    const dir = directory.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+    const file = path.posix.basename(pipelineFilename.trim().replace(/\\/g, "/"));
+    if (!dir || dir === ".")
+        return file;
+    return `${dir.replace(/\/+$/, "")}/${file}`;
+}
+export function bindPinnedBuildContext(current, build, sessionId) {
+    const base = isWorkshopDraftContext(current)
+        ? { ...current }
+        : { draft: build.draft };
+    const next = {
+        ...base,
+        draft: build.draft,
+        chatSessionId: sessionId,
+        buildId: build.id,
+    };
+    if (build.projectRoot)
+        next.projectRoot = build.projectRoot;
+    else
+        delete next.projectRoot;
+    if (build.projectRoot && build.relativePath) {
+        next.destination = destinationFromRelativePath(build.relativePath);
+    }
+    else {
+        delete next.destination;
+    }
+    return next;
+}
+function emitPointerChange(registry, sessionId, build) {
+    registry.getLiveTurn(sessionId)?.onPointerChange?.({
+        buildId: build.id,
+        draft: build.draft,
+    });
+}
+function movePinOntoBuild(registry, sessionId, build, storeRoot) {
+    const session = registry.get(sessionId);
+    if (session) {
+        session.setContext(bindPinnedBuildContext(session.getContext(), build, sessionId));
+    }
+    registry.setPinnedBuildId(sessionId, build.id);
+    enqueueSessionWrite(sessionId, () => {
+        updateWorkshopSessionActiveBuildId(storeRoot, sessionId, build.id);
+    });
+    emitPointerChange(registry, sessionId, build);
+}
+export function resolveLiveWorkshopBinding(context) {
+    if (!isWorkshopDraftContext(context) || !context.chatSessionId)
+        return null;
+    const live = liveBySession.get(context.chatSessionId);
+    if (!live)
+        return null;
+    return {
+        sessionId: context.chatSessionId,
+        registry: live.registry,
+        storeRoot: live.storeRoot,
+    };
+}
+/**
+ * Draft tools call this. Outside a workshop chat turn it does nothing.
+ * An unlinked chat turn fails the tool and does not create a build.
+ */
+export function rejectUnlinkedWorkshopDraftTool(context, toolName) {
+    if (!WORKSHOP_DRAFT_TOOL_NAMES.has(toolName))
+        return null;
+    if (!isWorkshopDraftContext(context) || !context.chatSessionId)
+        return null;
+    if (context.buildId)
+        return null;
+    return {
+        ok: false,
+        content: null,
+        error: WORKSHOP_UNLINKED_DRAFT_TOOL_ERROR,
+    };
+}
+/** Tied builds save to the stored path. Untitled builds keep the caller's destination. */
+export function resolvePinnedSaveDestination(context) {
+    if (!isWorkshopDraftContext(context) ||
+        !context.buildId ||
+        !context.chatSessionId) {
+        return null;
+    }
+    const live = liveBySession.get(context.chatSessionId);
+    if (!live)
+        return null;
+    const build = readWorkshopBuild(live.storeRoot, context.buildId);
+    if (!build?.projectRoot || !build.relativePath)
+        return null;
+    return destinationFromRelativePath(build.relativePath);
+}
+/** A successful save of an untitled build records the operator destination on that id. */
+export function recordPinnedWorkshopSave(context, saved) {
+    if (!isWorkshopDraftContext(context) ||
+        !context.buildId ||
+        !context.chatSessionId) {
+        return;
+    }
+    const live = liveBySession.get(context.chatSessionId);
+    if (!live)
+        return;
+    const build = readWorkshopBuild(live.storeRoot, context.buildId);
+    if (!build || (build.projectRoot && build.relativePath))
+        return;
+    const pipelineFilename = saved.pipelineFilename?.trim() ||
+        `${saved.draft.pipeline.id}.pipeline.yaml`;
+    updateWorkshopBuild(live.storeRoot, build.id, {
+        draft: saved.draft,
+        projectRoot: path.resolve(saved.projectRoot),
+        relativePath: relativePathFromDestination(saved.directory, pipelineFilename),
+    });
+}
+/**
+ * Create an untitled build and move this turn's pin onto it.
+ * Later edits in the turn persist on that id.
+ */
+export function pinWorkshopBuildOnCreate(input) {
+    const build = createWorkshopBuild(input.storeRoot, { draft: input.draft });
+    registerLiveWorkshopSession(input.sessionId, {
+        storeRoot: input.storeRoot,
+        registry: input.registry,
+    });
+    movePinOntoBuild(input.registry, input.sessionId, build, input.storeRoot);
+    return build;
+}
+/**
+ * Focus a build. When this turn already has a pin, update the pointer only.
+ * When the turn started with none, move the pin and the host onto that build.
+ */
+export function focusWorkshopBuildPointer(input) {
+    const build = getWorkshopBuild(input.storeRoot, input.buildId);
+    registerLiveWorkshopSession(input.sessionId, {
+        storeRoot: input.storeRoot,
+        registry: input.registry,
+    });
+    const pinned = input.registry.getPinnedBuildId(input.sessionId);
+    const turnLive = input.registry.getLiveTurn(input.sessionId);
+    const pinMoved = Boolean(turnLive) && !pinned;
+    if (pinMoved) {
+        movePinOntoBuild(input.registry, input.sessionId, build, input.storeRoot);
+    }
+    else {
+        enqueueSessionWrite(input.sessionId, () => {
+            updateWorkshopSessionActiveBuildId(input.storeRoot, input.sessionId, build.id);
+        });
+        if (turnLive)
+            emitPointerChange(input.registry, input.sessionId, build);
+    }
+    return { pinMoved, activeBuildId: build.id };
+}

package/examples/README.md

@@ -30,6 +30,7 @@ More CI-focused examples will follow this pattern (prepare context → run pipel
 | [generic-fan-in](generic-fan-in/) | Dummy diamond join; inspect keyed parent envelopes | `sf ui`, then `sf run` |
 | [stage-mcp](stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture | `sf validate`, then `sf run` from git root |
 | [playwright-mcp](playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) | `sf validate`, then `sf run` from git root |
+| [browser-session](browser-session/) | Saved browser login: check, human login only when logged out, then work; local fixture site | [README](browser-session/README.md), then `sf run` |
 | [context7-mcp](context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) | `sf validate`, then `sf run` from git root |
 | [feedback-loop](feedback-loop/) | Source-owned review loop (`continue` / `send_back`) | `sf validate`, then `sf run` |
 | [feature-loop](feature-loop/) | Epic-to-PR; two Clone Chains + `{ type: loop }` | `sf validate`, then `sf run` |
@@ -46,7 +47,7 @@ More CI-focused examples will follow this pattern (prepare context → run pipel
 
 Current wiring tours: [`route-wiring-smoke-test`](route-wiring-smoke-test/), [`route-if-tour`](route-if-tour/).
 
-Browse scope is declared in repo-root [`stageflow.yaml`](../stageflow.yaml). **`sf ui` started from any subdirectory** still uses `<repo>/.stageflow` for run state.
+Browse scope is declared in repo-root [`stageflow.yaml`](../stageflow.yaml). Cold Host (`sf ui` / `sf mcp`) also browses the packaged seeded root via [`examples/stageflow.yaml`](stageflow.yaml) (paths relative to `examples/`; wire `project_root: "examples"`). **`sf ui` started from any subdirectory** still uses the global durable root (`$STAGEFLOW_HOME`) for run state.
 
 ## Prerequisites (all examples)