stageflow 0.32.0 → 0.35.0

package/dist/hosted/sequencer.js

@@ -0,0 +1,129 @@
+import { redactString } from "../logging/redact.js";
+import { HostedRuntimeError } from "./errors.js";
+import { HOSTED_EVENT_SCHEMA_VERSION, } from "./types.js";
+export class HostedEventSequencer {
+    sink;
+    context;
+    timeoutMs;
+    attempts;
+    chain = Promise.resolve();
+    held = [];
+    holding = true;
+    sequence = 0;
+    runId = "";
+    failed = false;
+    failure;
+    constructor(sink, context, timeoutMs, attempts) {
+        this.sink = sink;
+        this.context = context;
+        this.timeoutMs = timeoutMs;
+        this.attempts = attempts;
+    }
+    setRunId(runId) {
+        this.runId = runId;
+    }
+    emit(body) {
+        if (this.failed)
+            return Promise.reject(this.failureError());
+        if (this.holding) {
+            return new Promise((resolve, reject) => {
+                this.held.push({ body, resolve, reject });
+            });
+        }
+        return this.enqueue(body);
+    }
+    emitNow(body) {
+        if (this.failed)
+            return Promise.reject(this.failureError());
+        return this.enqueue(body);
+    }
+    release() {
+        if (!this.holding)
+            return;
+        this.holding = false;
+        const queued = this.held;
+        this.held = [];
+        for (const item of queued) {
+            const run = this.chain.then(() => this.deliver(item.body));
+            this.chain = run.then(() => undefined, () => undefined);
+            void run.then(item.resolve, item.reject);
+        }
+    }
+    rejectHeld(error) {
+        this.holding = false;
+        const queued = this.held;
+        this.held = [];
+        for (const item of queued)
+            item.reject(error);
+    }
+    enqueue(body) {
+        const run = this.chain.then(() => this.deliver(body));
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async deliver(body) {
+        if (this.failed)
+            throw this.failureError();
+        const sequence = ++this.sequence;
+        const event = this.envelope(body, sequence);
+        let last;
+        for (let attempt = 1; attempt <= this.attempts; attempt += 1) {
+            try {
+                await withTimeout(this.sink.onEvent(event), this.timeoutMs);
+                return;
+            }
+            catch (error) {
+                last = error;
+            }
+        }
+        const message = redactString(errorMessage(last));
+        this.failed = true;
+        this.failure = { eventType: event.type, sequence, message };
+        throw this.failureError();
+    }
+    envelope(body, sequence) {
+        return {
+            schemaVersion: HOSTED_EVENT_SCHEMA_VERSION,
+            eventId: `${this.context.externalAttemptId}:${sequence}`,
+            sequence,
+            occurredAt: new Date().toISOString(),
+            runId: this.runId,
+            externalRunId: this.context.externalRunId,
+            externalAttemptId: this.context.externalAttemptId,
+            packageRevision: this.context.packageRevision,
+            ...(this.context.attributes !== undefined
+                ? { attributes: this.context.attributes }
+                : {}),
+            ...body,
+        };
+    }
+    failureError() {
+        const failure = this.failure;
+        return new HostedRuntimeError(failure?.message ?? "hosted event sink failed", {
+            code: "event_sink_failed",
+            externalRunId: this.context.externalRunId,
+            externalAttemptId: this.context.externalAttemptId,
+            ...(this.runId !== "" ? { runId: this.runId } : {}),
+            ...(failure !== undefined
+                ? { eventType: failure.eventType, sequence: failure.sequence }
+                : {}),
+        });
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function withTimeout(work, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error("hosted event sink timed out"));
+        }, timeoutMs);
+        work.then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}

package/dist/hosted/translate.d.ts

@@ -0,0 +1,3 @@
+import type { StageLogLine } from "../agent/activity.js";
+import type { HostedEventBody } from "./types.js";
+export declare function translateStageEvent(stageId: string, event: StageLogLine, attempt: number): HostedEventBody | undefined;

package/dist/hosted/translate.js

@@ -0,0 +1,43 @@
+import { redactString } from "../logging/redact.js";
+const ACTIVITY_EVENTS = new Set([
+    "agent_start",
+    "agent_end",
+    "turn_start",
+    "tool_start",
+    "tool_end",
+    "tool_progress",
+    "message",
+    "operator_prompt",
+    "operator_answer",
+]);
+function redactActivity(event) {
+    return JSON.parse(redactString(JSON.stringify(event)));
+}
+export function translateStageEvent(stageId, event, attempt) {
+    if (ACTIVITY_EVENTS.has(event.event)) {
+        return {
+            type: "stage.activity",
+            stageId,
+            attempt,
+            activity: redactActivity(event),
+        };
+    }
+    switch (event.event) {
+        case "started":
+            return { type: "stage.started", stageId, attempt };
+        case "waiting_for_input":
+            return { type: "stage.waiting", stageId, attempt };
+        case "succeeded":
+            return { type: "stage.succeeded", stageId, attempt };
+        case "failed":
+        case "interrupted":
+            return {
+                type: "stage.failed",
+                stageId,
+                attempt,
+                reason: redactString(event.reason),
+            };
+        default:
+            return undefined;
+    }
+}

package/dist/hosted/types.d.ts

@@ -0,0 +1,108 @@
+import type { StageActivityEvent } from "../agent/activity.js";
+import type { HostedErrorCode } from "./errors.js";
+export declare const HOSTED_EVENT_SCHEMA_VERSION: 1;
+/** One sink call is attempted this many times. Delivery is at least once, not exactly once. */
+export declare const HOSTED_DELIVERY_ATTEMPTS = 2;
+/** Bound for a single sink call. The private sink and Cloud worker own further retries. */
+export declare const DEFAULT_EVENT_DELIVERY_TIMEOUT_MS = 10000;
+/**
+ * After cancellation or timeout, Core waits at most this long for in-flight
+ * stage work to stop. `StagePort` handles must stop inside `close()`.
+ */
+export declare const HOSTED_CANCEL_GRACE_MS = 5000;
+export type HostedRunContext = {
+    /** Opaque Cloud run id. Core copies it and does not interpret it. */
+    externalRunId: string;
+    /** Opaque Cloud attempt id. Core copies it and does not interpret it. */
+    externalAttemptId: string;
+    /** Revision of the package Cloud already materialized. */
+    packageRevision: string;
+    /** Extra non-secret correlation strings. */
+    attributes?: Readonly<Record<string, string>>;
+};
+export type HostedPipelineInput = {
+    packageRoot: string;
+    pipeline: string;
+    taskYaml: string;
+    context: HostedRunContext;
+    signal?: AbortSignal;
+    maxActiveStagesPerRun?: number;
+    /** Wall-clock limit for the hosted run. Omit for no hosted-level limit. */
+    timeoutMs?: number;
+};
+export type HostedExecutionReceipt = {
+    coreVersion: string;
+    eventSchemaVersion: typeof HOSTED_EVENT_SCHEMA_VERSION;
+    packageRevision: string;
+    executionMode: "inline";
+    startedAt: string;
+    finishedAt: string;
+};
+export type HostedPipelineResult = {
+    /** Null when the run failed before Core created a local run. */
+    runId: string | null;
+    externalRunId: string;
+    externalAttemptId: string;
+    status: "succeeded" | "failed" | "cancelled" | "waiting";
+    code?: HostedErrorCode;
+    reason?: string;
+    /** Present once a local run exists. Caller exports artifacts from here. */
+    workspaceDir?: string;
+    receipt: HostedExecutionReceipt;
+};
+export type HostedEventEnvelope = {
+    schemaVersion: typeof HOSTED_EVENT_SCHEMA_VERSION;
+    eventId: string;
+    sequence: number;
+    occurredAt: string;
+    runId: string;
+    externalRunId: string;
+    externalAttemptId: string;
+    packageRevision: string;
+    attributes?: Readonly<Record<string, string>>;
+};
+export type HostedRunEvent = HostedEventEnvelope & ({
+    type: "run.created";
+} | {
+    type: "run.started";
+} | {
+    type: "stage.started";
+    stageId: string;
+    attempt: number;
+} | {
+    type: "stage.activity";
+    stageId: string;
+    attempt: number;
+    activity: StageActivityEvent;
+} | {
+    type: "stage.waiting";
+    stageId: string;
+    attempt: number;
+} | {
+    type: "stage.succeeded";
+    stageId: string;
+    attempt: number;
+} | {
+    type: "stage.failed";
+    stageId: string;
+    attempt: number;
+    reason?: string;
+} | {
+    type: "run.succeeded";
+    receipt: HostedExecutionReceipt;
+} | {
+    type: "run.failed";
+    code?: HostedErrorCode;
+    reason?: string;
+    receipt: HostedExecutionReceipt;
+} | {
+    type: "run.cancelled";
+    reason?: string;
+    receipt: HostedExecutionReceipt;
+});
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type HostedEventBody = DistributiveOmit<HostedRunEvent, keyof HostedEventEnvelope>;
+export interface HostedEventSink {
+    onEvent(event: HostedRunEvent): Promise<void>;
+}
+export {};

package/dist/hosted/types.js

@@ -0,0 +1,10 @@
+export const HOSTED_EVENT_SCHEMA_VERSION = 1;
+/** One sink call is attempted this many times. Delivery is at least once, not exactly once. */
+export const HOSTED_DELIVERY_ATTEMPTS = 2;
+/** Bound for a single sink call. The private sink and Cloud worker own further retries. */
+export const DEFAULT_EVENT_DELIVERY_TIMEOUT_MS = 10_000;
+/**
+ * After cancellation or timeout, Core waits at most this long for in-flight
+ * stage work to stop. `StagePort` handles must stop inside `close()`.
+ */
+export const HOSTED_CANCEL_GRACE_MS = 5_000;

package/dist/index.d.ts

@@ -5,10 +5,18 @@ export { resolveStageflowContext, projectContextFromStageflow, type StageflowCon
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
-export type { AgentPort } from "./agent/port.js";
+export type { StagePort, StageHandle, StageHandleEvent, StageRunInput, StageRunResult, } from "./agent/port.js";
+export { createPiStagePort } from "./agent/resolveStagePort.js";
+export { createPiAgentPort, resolveAgentPort, type AgentPort, } from "./operatorAgent/agentPort.js";
+export { configurePiProviderApiKey } from "./agent/providerAuth.js";
 export type { StageActivityEvent, StageLogLine } from "./agent/activity.js";
 export type { StageRoots } from "./runtime/stageRoots.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
+export { createHostedRuntime, type HostedRuntime, } from "./hosted/runtime.js";
+export { HostedRuntimeError, HOSTED_ERROR_CODES } from "./hosted/errors.js";
+export type { HostedErrorCode } from "./hosted/errors.js";
+export { HOSTED_EVENT_SCHEMA_VERSION, HOSTED_DELIVERY_ATTEMPTS, DEFAULT_EVENT_DELIVERY_TIMEOUT_MS, HOSTED_CANCEL_GRACE_MS, } from "./hosted/types.js";
+export type { HostedRunContext, HostedPipelineInput, HostedPipelineResult, HostedExecutionReceipt, HostedEventEnvelope, HostedRunEvent, HostedEventSink, } from "./hosted/types.js";
 export { createRunStore } from "./runstore/createStore.js";
 export type { RunStoreConfig, RunStoreKind } from "./runstore/createStore.js";
 export type { RunStore, RunSummary, RunDetail, RunMeta, RunStatus, StageSnapshot, StageLogEvent, CreatedRun, } from "./runstore/port.js";

package/dist/index.js

@@ -4,7 +4,13 @@ export { resolveProjectContext, legacyProjectContext, } from "./project/resolveP
 export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
+export { createPiStagePort } from "./agent/resolveStagePort.js";
+export { createPiAgentPort, resolveAgentPort, } from "./operatorAgent/agentPort.js";
+export { configurePiProviderApiKey } from "./agent/providerAuth.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
+export { createHostedRuntime, } from "./hosted/runtime.js";
+export { HostedRuntimeError, HOSTED_ERROR_CODES } from "./hosted/errors.js";
+export { HOSTED_EVENT_SCHEMA_VERSION, HOSTED_DELIVERY_ATTEMPTS, DEFAULT_EVENT_DELIVERY_TIMEOUT_MS, HOSTED_CANCEL_GRACE_MS, } from "./hosted/types.js";
 export { createRunStore } from "./runstore/createStore.js";
 export { deriveStatusFromStages } from "./runstore/port.js";
 export { RunManager } from "./runtime/runManager.js";

package/dist/mcp/getStartedTool.js

@@ -29,9 +29,12 @@ export function registerGetStartedTool(server, deps) {
             task_count: tasks.items.filter((t) => t.project_root === root.project_root)
                 .length,
         }));
-        const firstRoot = catalog_roots.find((r) => r.kind === "seeded") ?? catalog_roots[0];
-        const samplePipeline = pipelines.items.find((p) => p.project_root === firstRoot?.project_root);
-        const sampleTask = tasks.items.find((t) => t.project_root === firstRoot?.project_root);
+        const authoringRoot = catalog_roots.find((r) => r.kind === "workspace" && r.read_only !== true) ??
+            catalog_roots.find((r) => r.kind === "registered") ??
+            catalog_roots[0];
+        const browseRoot = catalog_roots.find((r) => r.kind === "seeded") ?? authoringRoot;
+        const samplePipeline = pipelines.items.find((p) => p.project_root === browseRoot?.project_root);
+        const sampleTask = tasks.items.find((t) => t.project_root === browseRoot?.project_root);
         return textResult({
             host: { version: PACKAGE_VERSION },
             providers: deps.providerAuthContext
@@ -42,16 +45,22 @@ export function registerGetStartedTool(server, deps) {
             next_steps: [
                 {
                     tool: "list_pipelines",
-                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                    args: authoringRoot
+                        ? { project_root: authoringRoot.project_root }
+                        : {},
                 },
                 {
                     tool: "list_tasks",
-                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                    args: authoringRoot
+                        ? { project_root: authoringRoot.project_root }
+                        : {},
                 },
                 {
                     tool: "start_run",
                     args: {
-                        ...(firstRoot ? { project_root: firstRoot.project_root } : {}),
+                        ...(authoringRoot
+                            ? { project_root: authoringRoot.project_root }
+                            : {}),
                         pipeline: samplePipeline?.path ?? "pipelines/demo.pipeline.yaml",
                         task_path: sampleTask?.path ?? "tasks/demo.task.yaml",
                     },

package/dist/mcp/triggerTools.js

@@ -63,10 +63,7 @@ export function registerTriggerTools(server, deps) {
         description: "List catalog-declared triggers (same source as GET /api/triggers): manual/schedule/event kind, enabled, and store-recorded last_fired_at/last_run_id/next_run_at when present.",
         inputSchema: z.object({}),
     }, async () => {
-        const items = await loadCatalogTriggers(cwd, store);
-        if (items === undefined) {
-            return textResult({ error: "No Stageflow catalog found", status: 404 }, true);
-        }
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
         return textResult({ triggers: items });
     });
     server.registerTool("get_trigger", {
@@ -75,10 +72,7 @@ export function registerTriggerTools(server, deps) {
             id: z.string(),
         }),
     }, async ({ id }) => {
-        const items = await loadCatalogTriggers(cwd, store);
-        if (items === undefined) {
-            return textResult({ error: "No Stageflow catalog found", status: 404 }, true);
-        }
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
         const found = items.find((item) => item.id === id);
         if (!found) {
             return textResult({ error: `Trigger not found: ${id}`, status: 404 }, true);

package/dist/operatorAgent/agentPort.d.ts

@@ -0,0 +1,11 @@
+import { type LiveWorkshopOperatorHostOptions } from "./piModel.js";
+import type { OperatorAgentHost } from "./types.js";
+export declare const AGENT_PORT_BACKENDS: readonly ["pi"];
+export type AgentPortBackendId = (typeof AGENT_PORT_BACKENDS)[number];
+/** Stays up, takes a message, and answers. Stage runs stay on StagePort. */
+export type AgentPort = OperatorAgentHost;
+export type AgentPortOptions = LiveWorkshopOperatorHostOptions & {
+    backend?: AgentPortBackendId;
+};
+export declare function createPiAgentPort(options: LiveWorkshopOperatorHostOptions): AgentPort;
+export declare function resolveAgentPort(options: AgentPortOptions): AgentPort;

package/dist/operatorAgent/agentPort.js

@@ -0,0 +1,12 @@
+import { createLiveWorkshopOperatorHost, } from "./piModel.js";
+export const AGENT_PORT_BACKENDS = ["pi"];
+export function createPiAgentPort(options) {
+    return createLiveWorkshopOperatorHost(options);
+}
+export function resolveAgentPort(options) {
+    const backend = options.backend ?? "pi";
+    switch (backend) {
+        case "pi":
+            return createPiAgentPort(options);
+    }
+}

package/dist/operatorAgent/index.d.ts

@@ -1,6 +1,7 @@
 export type { AcceptProposalResult, OperatorAgentContextAdapter, OperatorAgentHost, OperatorAgentProfile, OperatorAgentProposal, OperatorAgentSession, OperatorAgentSessionEvent, OperatorAgentTool, OperatorAgentToolContext, OperatorAgentToolResult, ProposalArtifactDiff, UndoMutationResult, WorkshopDraftContext, WorkshopToolActivityUpdate, } from "./types.js";
 export { createOperatorAgentHost, invokeProfileTool, type OperatorAgentModel, type OperatorAgentModelTurn, } from "./host.js";
 export { createFakeOperatorAgentModel, createWorkshopOperatorHost, type FakeOperatorTurn, type WorkshopOperatorHostOptions, } from "./fakeHost.js";
+export { AGENT_PORT_BACKENDS, createPiAgentPort, resolveAgentPort, type AgentPortBackendId, type AgentPort, type AgentPortOptions, } from "./agentPort.js";
 export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, type LiveWorkshopOperatorHostOptions, type PiOperatorAgentModel, type PiOperatorAgentModelOptions, type PiOperatorOpenSessionInput, type PiOperatorSessionHandle, type WorkshopTranscriptSeedMessage, } from "./piModel.js";
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, type DocsRetrievalHit, type DocsRetrievalResult, type DocsRetriever, } from "./docsRetrieval.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";

package/dist/operatorAgent/index.js

@@ -1,5 +1,6 @@
 export { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
 export { createFakeOperatorAgentModel, createWorkshopOperatorHost, } from "./fakeHost.js";
+export { AGENT_PORT_BACKENDS, createPiAgentPort, resolveAgentPort, } from "./agentPort.js";
 export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, } from "./piModel.js";
 export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, } from "./docsRetrieval.js";
 export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";

package/dist/operatorAgent/piModel.js

@@ -1,7 +1,8 @@
 /**
  * Live Pi-backed OperatorAgentModel for Workshop Author.
  *
- * Uses the shared Pi session factory (not AgentPort). Workshop tools only —
+ * Pi backend behind AgentPort, using the shared session factory. Not a StagePort.
+ * Workshop tools only —
  * resolveWorkshopToolNames / assertWorkshopToolsExcludeDiskShell. Durable Pi
  * session per host tool-context (R7). Restart: new Pi + transcript replay (KTD7).
  */
@@ -10,7 +11,7 @@ import path from "node:path";
 import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { createPiAgentSession, createSealedResourceLoader, resolveWorkshopToolNames, } from "../agent/piSessionFactory.js";
-import { cursorBridgePrompt } from "../agent/cursorProvider.js";
+import { bindCursorApiKey, cursorBridgePrompt } from "../agent/cursorProvider.js";
 import { findProviderSupport } from "../agent/providerSupport.js";
 import "../agent/cursorProvider.js";
 import { logger as rootLogger } from "../logging/logger.js";
@@ -158,8 +159,16 @@ function formatTranscriptReplay(transcript) {
         ...lines,
     ].join("\n");
 }
+function processDataAuthPath() {
+    return path.join(globalStageflowHome(), "agent", "auth.json");
+}
 function authNotConfiguredError(authPath) {
-    return new Error(`Workshop Author provider auth is not configured (auth file missing or empty: ${authPath}). Configure credentials via \`sf providers\` / the operator console Providers page, then retry.`);
+    const dataAuth = processDataAuthPath();
+    const unusedDataFile = path.resolve(dataAuth) !== path.resolve(authPath) &&
+        isUsableAuthFile(dataAuth)
+        ? ` A usable auth file at ${dataAuth} in the process data directory is not used.`
+        : "";
+    return new Error(`Workshop Author provider auth is not configured (auth file missing or empty: ${authPath}).${unusedDataFile} Configure credentials via \`sf providers\` / the operator console Providers page, then retry.`);
 }
 function syncAgentMessages(session, sessionManager) {
     if (session.agent?.state) {
@@ -185,15 +194,23 @@ function extractAssistantText(message) {
     return parts.length > 0 ? parts.join("") : undefined;
 }
 async function openDefaultPiSession(input) {
-    if (!isUsableAuthFile(input.authPath)) {
+    const provider = findProviderSupport(input.modelId);
+    if (!provider && !isUsableAuthFile(input.authPath)) {
         throw authNotConfiguredError(input.authPath);
     }
-    const provider = findProviderSupport(input.modelId);
     const additionalExtensionPaths = [];
     let restoreProvider;
+    let restoreCursorKey;
+    const bindCursor = (modelId) => {
+        const restore = bindCursorApiKey(modelId);
+        if (restore)
+            restoreCursorKey = restore;
+    };
+    bindCursor(input.modelId);
     if (provider) {
         const prepared = provider.prepare(input.modelId);
         if (prepared.error) {
+            restoreCursorKey?.();
             throw new Error(prepared.error);
         }
         additionalExtensionPaths.push(...prepared.extensionPaths);
@@ -260,6 +277,7 @@ async function openDefaultPiSession(input) {
         const applyModel = async (modelId) => {
             if (modelId === currentModelId)
                 return;
+            bindCursor(modelId);
             const provider = findProviderSupport(modelId);
             if (provider) {
                 const prepared = provider.prepare(modelId);
@@ -294,6 +312,7 @@ async function openDefaultPiSession(input) {
                 catch {
                     // best-effort
                 }
+                restoreCursorKey?.();
                 restoreProvider?.();
             },
         };
@@ -305,6 +324,7 @@ async function openDefaultPiSession(input) {
         catch {
             // best-effort
         }
+        restoreCursorKey?.();
         restoreProvider?.();
         throw err;
     }
@@ -522,7 +542,7 @@ export function createLiveWorkshopOperatorHost(options) {
     }), [
         createWorkshopAuthorProfile({
             retriever,
-            projectRoot: projectRoot ?? cwd,
+            ...(projectRoot !== undefined ? { projectRoot } : {}),
         }),
     ]);
 }

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.d.ts

@@ -3,4 +3,4 @@
  * guidance and public YAML catalog concepts. First-class Workshop editors
  * cover the core path; advanced topics are explain-only.
  */
-export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";
+export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.\n- Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id \u2014 not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML. After save, use published.* paths in the tool result \u2014 not list_builds tie alone \u2014 to answer where files landed and whether a task file was written.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) \u2014 never on a uses: wrapper.\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.js

@@ -30,12 +30,13 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 ## Tools
 - Never invent a disk path; never use bash/write/edit.
 - Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace — avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose→Accept gating is superseded by immediate mutate + soft undo.
-- list_builds returns the same rows as the studio and does not create a build. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.
+- list_builds returns the same rows as the studio and does not create a build; use catalogListed before telling the operator a pipeline or task appears on Tasks or Pipelines. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.
+- Build tie (projectRoot + relativePath on a row) is the last saved catalog anchor for that build id — not every path on disk counts for Tasks (e.g. image package roots or paths outside stageflow.yaml scan). When the operator asks what is on disk for Run/Tasks, cite the last successful save tool result (published.project_root_path, published.pipeline_path, published.task_path) or a catalogListed row. Draft-only task changes are not on disk until save returns task_path.
 - Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.
 - Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.
 - Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).
 - Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.
-- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML.
+- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML. After save, use published.* paths in the tool result — not list_builds tie alone — to answer where files landed and whether a task file was written.
 - Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, …) — not product stage types.
 - Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.
 - Core path = first-class Workshop editors. Advanced topics below are explain-only — do not invent Workshop editors for them.
@@ -50,6 +51,7 @@ Bad: a paragraph of pipeline theory, a numbered plan, and three questions at onc
 
 ## Core: prompts
 - Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).
+- Optional skill: belongs on the stage body (create_stage / edit_stage body or stage file) — never on a uses: wrapper.
 - Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.
 - Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.
 - Gated sequence: write artifact → ask_operator → emit only after accept; revise on reject in the same attempt.