stageflow 0.25.0 → 0.27.0

package/README.md

@@ -38,7 +38,8 @@ The same pipeline runs three ways without rewriting anything:
 - **Standalone stage execution** — run a single stage directly with `run_stage` (MCP tool, `sf run-stage` CLI, or the A2A `run_stage` operation), no pipeline file required; chain calls with `envelope_ref` (one or many prior results) instead of a pipeline DAG
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
 - **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
-- **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
+- **Definition-time graph view** — `sf graph --pipeline <path>` prints how a pipeline is wired before any run (terminal diagram or `--json`)
+- **SQLite run store** — global `~/.stageflow/.stageflow/` state plus per-run workspaces, shared across every project since Stageflow became a single auto-starting service
 
 ## Architecture at a glance
 
@@ -97,6 +98,8 @@ sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
 
 Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
 
+**Docker Compose** (UI + MCP in one Host): copy [`.env.example`](.env.example) → `.env`, set `STAGEFLOW_CONTROL_TOKEN`, then `docker compose up --build -d`. Checklist: [docs/docker.md](docs/docker.md#local-try-compose).
+
 ## Connect a model provider
 
 Each stage sets a **`model`** id in YAML (e.g. `anthropic/claude-sonnet-4-5`). The matching provider must be authenticated before runs succeed — `sf validate` does not check auth.
@@ -185,12 +188,14 @@ See [docs/ci.md](docs/ci.md) for the full CI recipe and [`.github/actions/sf-run
 
 ## State
 
-Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository (SQLite + per-run workspaces under `.stageflow/runs/`). Global config and `sf_owned` auth live under **`~/.stageflow/`**. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
+Runtime state (SQLite run store + per-run workspaces) is **global** — `~/.stageflow/.stageflow/` — shared across every project on the machine, since Stageflow became a single auto-starting service. Global config and `sf_owned` auth live directly under **`~/.stageflow/`**; per-project settings (`maxConcurrent`, `credentialSource`) still live at `<git-root>/.stageflow/settings.json`. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
 
 ## MCP
 
 Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on boot). Sessions are the default. Point a Cursor (or other) MCP client at that URL. Do not run both hosts against the same store.
 
+Stageflow runs as **one global auto-starting service per machine** (not one process per project): `sf run`, `sf run-stage`, and `sf runs *` health-probe the well-known port and spawn the service headlessly if nothing answers, so you do not have to start `sf ui`/`sf mcp` by hand before using the CLI.
+
 HITL-aware tools include `wait_run`, `answer_gate`, `list_waiting`, and `decide_feedback_loop`. Inspect tools (`list_providers`, `list_models`, `describe_pipeline`, …) are read-only. `run_stage` runs a single stage directly, no pipeline file required — see [Standalone stages](#standalone-stages) below. Full tool list: [docs/mcp.md](docs/mcp.md).
 
 Stages use project `.mcp.json` plus stage `mcp` names. See [YAML catalog — Stage MCP](docs/yaml-catalog.md#stage-mcp).
@@ -248,13 +253,15 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
 | [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
 | [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
-| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf run-stage`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
+| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf run-stage`, `sf graph`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
 | [docs/envelopes.md](docs/envelopes.md) | Handoff envelope contract |
+| [docs/verified-stage-execution.md](docs/verified-stage-execution.md) | After-phase `verify`, evidence, and `on_verify_fail` repair / manual recovery |
 | [docs/hitl.md](docs/hitl.md) | Gate kinds, `--skip-gates`, exit code `2` |
 | [docs/ci.md](docs/ci.md) | `--json`, env vars, GitHub Actions |
 | [docs/mcp.md](docs/mcp.md) | MCP tool reference, including standalone `run_stage` |
 | [docs/a2a.md](docs/a2a.md) | Publish pipelines for other agents to call over JSON-RPC (A2A), plus the wildcard-access `run_stage` operation |
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
+| [docs/docker.md](docs/docker.md) | Docker Compose local try, image pull/run, backup, self-hosting |
 | [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
 | [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
 

package/dist/a2a/contracts.d.ts

@@ -55,6 +55,7 @@ export type RunStageCommand = {
     contextId?: string;
     stage?: string | Record<string, unknown>;
     pipeline?: string | Record<string, unknown>;
+    project_root?: string;
     task_path?: string;
     task?: TaskFileInput;
     envelope_ref?: EnvelopeRefInput | EnvelopeRefInput[];

package/dist/a2a/contracts.js

@@ -57,6 +57,7 @@ const runStageDataPart = z
     operation: z.literal("run_stage"),
     stage: z.union([z.string().min(1), z.record(z.string(), z.unknown())]).optional(),
     pipeline: z.union([z.string().min(1), z.record(z.string(), z.unknown())]).optional(),
+    project_root: z.string().optional(),
     task_path: z.string().optional(),
     task: taskFileSchema.optional(),
     envelope_ref: z.union([envelopeRefSchema, z.array(envelopeRefSchema).min(1)]).optional(),

package/dist/a2a/registry.d.ts

@@ -6,6 +6,8 @@ declare const publicationSchema: z.ZodObject<{
     project_root: z.ZodString;
     pipeline: z.ZodString;
     goal: z.ZodString;
+    repository: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
     allowed_callers: z.ZodArray<z.ZodString>;
     input_schema: z.ZodString;
     results: z.ZodObject<{

package/dist/a2a/registry.js

@@ -13,6 +13,8 @@ const publicationSchema = z.object({
     project_root: z.string().min(1),
     pipeline: z.string().min(1),
     goal: z.string().trim().min(1),
+    repository: z.string().trim().min(1).optional(),
+    ref: z.string().trim().min(1).optional(),
     allowed_callers: z.array(identifier).min(1),
     input_schema: z.string().min(1),
     results: z.object({
@@ -21,7 +23,24 @@ const publicationSchema = z.object({
         artifacts: z.array(z.string().regex(/^[^/\\.][^/\\]*$/)).default([]),
     }).strict(),
     caller_answerable_stages: z.array(identifier).default([]),
-}).strict();
+}).strict().superRefine((data, ctx) => {
+    const hasRepo = data.repository !== undefined;
+    const hasRef = data.ref !== undefined;
+    if (hasRepo && !hasRef) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "repository requires ref",
+            path: ["ref"],
+        });
+    }
+    if (hasRef && !hasRepo) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "ref requires repository",
+            path: ["repository"],
+        });
+    }
+});
 const configSchema = z.object({
     version: z.literal(1),
     public_url: z.string().url(),

package/dist/a2a/server.d.ts

@@ -4,6 +4,7 @@ import { AgentCard } from "@a2a-js/sdk";
 import type { RunStore } from "../runstore/port.js";
 import type { RunManager } from "../runtime/runManager.js";
 import { type PublicationRegistry } from "./registry.js";
+import type { A2aStore } from "./store.js";
 export declare const A2A_BODY_LIMIT: number;
 export declare function publicationCard(registry: PublicationRegistry, caller: string): AgentCard;
 export type A2aRuntime = {
@@ -12,11 +13,17 @@ export type A2aRuntime = {
     rootDir: string;
     /** The SqliteRunStore's own connection to `state.db`, when the caller constructed one via `createRunStoreWithConnection`. */
     connection?: Database.Database;
+    /** Shared A2A store when the Host composition root already opened one for delete_run. */
+    a2aStore?: A2aStore;
 };
 export type A2aHost = {
     status: {
         state: "disabled" | "enabled" | "configuration_error";
         configPath?: string;
+        error?: {
+            code: string;
+            message: string;
+        };
     };
     handle(req: HttpIncomingMessage, res: ServerResponse, pathname: string): Promise<boolean>;
     /** Deletes expired terminal tasks/artifacts and message tombstones. A no-op when A2A is not enabled. */

package/dist/a2a/server.js

@@ -210,10 +210,13 @@ export async function createA2aHost(runtime, configPath, env = process.env) {
             registry = await loadPublicationRegistry(configPath, env);
             status.configPath = registry.configPath;
             status.state = "enabled";
-            invocations = createA2aInvocations(registry, runtime.manager, runtime.runStore, runtime.rootDir, runtime.connection);
+            invocations = createA2aInvocations(registry, runtime.manager, runtime.runStore, runtime.rootDir, runtime.connection, undefined, runtime.a2aStore);
         }
-        catch {
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
             status.state = "configuration_error";
+            status.error = { code: "a2a_configuration_error", message };
+            console.error(`stageflow: A2A configuration error: ${message}`);
         }
     }
     const sweep = invocations

package/dist/a2a/service.d.ts

@@ -94,4 +94,4 @@ export declare class A2aInvocations {
     private buildTask;
     private projectTask;
 }
-export declare function createA2aInvocations(registry: PublicationRegistry, manager: RunManager, runStore: RunStore, rootDir: string, connection?: Database.Database, rateLimiter?: RateLimiter): A2aInvocations;
+export declare function createA2aInvocations(registry: PublicationRegistry, manager: RunManager, runStore: RunStore, rootDir: string, connection?: Database.Database, rateLimiter?: RateLimiter, a2aStore?: A2aStore): A2aInvocations;

package/dist/a2a/service.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { readRunArtifactBytes, artifactMediaType } from "../mcp/readArtifact.js";
+import { CatalogPathError, resolveCatalogRelativePath, resolveCatalogStartInput, } from "../config/catalogRelativePath.js";
 import { waitRun } from "../mcp/waitRun.js";
 import { readYamlObject } from "../config/readYamlObject.js";
 import { payloadInstanceMismatch } from "../envelope/payloadSchema.js";
@@ -126,7 +126,18 @@ export class A2aInvocations {
         }
         const taskId = existingTask?.task_id ?? newTaskId();
         const contextIdResolved = existingTask?.context_id ?? this.store.ensureContext(caller.id, contextId);
-        const result = await this.manager.startRunOnce({ pipeline: publication.pipeline, task: { id: taskId, goal: publication.goal, input: input } }, { key: submissionKey, requestHash: hash });
+        const result = await this.manager.startRunOnce({
+            pipeline: publication.pipeline,
+            task: {
+                id: taskId,
+                goal: publication.goal,
+                input: input,
+                ...(publication.repository !== undefined
+                    ? { repository: publication.repository }
+                    : {}),
+                ...(publication.ref !== undefined ? { ref: publication.ref } : {}),
+            },
+        }, { key: submissionKey, requestHash: hash });
         if (!result.ok) {
             throw mapStartFailure(result);
         }
@@ -143,7 +154,13 @@ export class A2aInvocations {
             if (result.done) {
                 void result.done
                     .catch(() => undefined)
-                    .then(() => this.maybeFinalize(this.store.getTask(taskId)));
+                    .then(() => {
+                    const row = this.store.getTask(taskId);
+                    if (!row)
+                        return;
+                    return this.maybeFinalize(row);
+                })
+                    .catch(() => undefined);
             }
         }
         this.store.recordMessage({ callerId: caller.id, messageId, taskId, operation: "invoke", requestHash: hash, outcome: { ok: true } });
@@ -176,12 +193,29 @@ export class A2aInvocations {
         }
         let pipelineArg;
         let resultStageId;
+        let runProjectRoot;
         if (cmd.stage !== undefined) {
             let stageBody;
             if (typeof cmd.stage === "string") {
                 if (!cmd.stage.trim())
                     throw new A2aApplicationError("invalid-input", "stage is required");
-                const absPath = path.resolve(this.rootDir, cmd.stage);
+                let absPath = "";
+                try {
+                    const { wireRoot, roots } = await resolveCatalogStartInput({ store: this.runStore }, cmd.project_root);
+                    runProjectRoot = wireRoot.path;
+                    absPath = resolveCatalogRelativePath({
+                        inputPath: cmd.stage,
+                        projectRoot: wireRoot.project_root,
+                        roots,
+                        fieldName: "stage",
+                    }).absolutePath;
+                }
+                catch (err) {
+                    if (err instanceof CatalogPathError) {
+                        throw new A2aApplicationError("invalid-input", err.message);
+                    }
+                    throw err;
+                }
                 try {
                     stageBody = await readYamlObject(absPath);
                 }
@@ -242,7 +276,11 @@ export class A2aInvocations {
         const contextIdResolved = existingTask?.context_id ?? this.store.ensureContext(caller.id, cmd.contextId);
         let result;
         try {
-            result = await this.manager.startRunOnce({ pipeline: pipelineArg, task: taskInput }, { key: submissionKey, requestHash: hash });
+            result = await this.manager.startRunOnce({
+                pipeline: pipelineArg,
+                task: taskInput,
+                ...(runProjectRoot !== undefined ? { projectRoot: runProjectRoot } : {}),
+            }, { key: submissionKey, requestHash: hash });
         }
         catch (err) {
             if (err instanceof PipelineValidationError) {
@@ -268,7 +306,13 @@ export class A2aInvocations {
             if (result.done) {
                 void result.done
                     .catch(() => undefined)
-                    .then(() => this.maybeFinalize(this.store.getTask(taskId)));
+                    .then(() => {
+                    const row = this.store.getTask(taskId);
+                    if (!row)
+                        return;
+                    return this.maybeFinalize(row);
+                })
+                    .catch(() => undefined);
             }
         }
         this.store.recordMessage({ callerId: caller.id, messageId: cmd.messageId, taskId, operation: "run_stage", requestHash: hash, outcome: { ok: true } });
@@ -491,6 +535,11 @@ function mapStartFailure(result) {
     }
     return new A2aApplicationError("invalid-input", result.reason);
 }
-export function createA2aInvocations(registry, manager, runStore, rootDir, connection, rateLimiter) {
-    return new A2aInvocations(registry, manager, runStore, rootDir, new A2aStore(rootDir, connection), rateLimiter);
+export function createA2aInvocations(registry, manager, runStore, rootDir, connection, rateLimiter, a2aStore) {
+    const store = a2aStore ??
+        (connection !== undefined ? new A2aStore(rootDir, connection) : undefined);
+    if (!store) {
+        throw new Error("A2A requires the Host SQLite connection");
+    }
+    return new A2aInvocations(registry, manager, runStore, rootDir, store, rateLimiter);
 }

package/dist/a2a/store.d.ts

@@ -51,12 +51,11 @@ export declare class A2aStore {
     private readonly artifactsRoot;
     private readonly ownsConnection;
     /**
-     * `connection`, when passed, is the SqliteRunStore's own connection to the same `state.db` file
-     * (see `createRunStoreWithConnection`) so the two stores share one transaction domain. Falls
-     * back to opening its own connection when no shared one is available (e.g. a caller-supplied
-     * non-SQLite `RunStore` in bootstrap).
+     * Uses the SqliteRunStore connection to the same `state.db` file so the two stores share one
+     * transaction domain. The Host must open the run store in migrate mode before constructing
+     * A2aStore. Additive `kind` / `result_stage_id` columns for run_stage are applied here.
      */
-    constructor(rootDir: string, connection?: Database.Database);
+    constructor(rootDir: string, connection: Database.Database);
     /**
      * Additive migration for a `state.db` created before the run_stage A2A
      * operation existed: `CREATE TABLE IF NOT EXISTS` above never alters an
@@ -103,4 +102,8 @@ export declare class A2aStore {
         removedTasks: number;
         removedMessages: number;
     }>;
+    /** Deletes every A2A task (and frozen artifact files) bound to a Stageflow run. */
+    deleteByRunId(runId: string): Promise<{
+        removedTasks: number;
+    }>;
 }

package/dist/a2a/store.js

@@ -1,57 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
-import Database from "better-sqlite3";
-import { storeRootFor } from "../runstore/paths.js";
+import { resolveStoreRoot } from "../runstore/paths.js";
 import { MESSAGE_TOMBSTONE_RETENTION_MS, TERMINAL_RETENTION_MS } from "./limits.js";
-const SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS a2a_contexts (
-  context_id TEXT PRIMARY KEY,
-  caller_id TEXT NOT NULL,
-  created_at TEXT NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS a2a_tasks (
-  task_id TEXT PRIMARY KEY,
-  context_id TEXT NOT NULL,
-  caller_id TEXT NOT NULL,
-  publication_id TEXT NOT NULL,
-  publication_revision TEXT NOT NULL,
-  submission_key TEXT NOT NULL UNIQUE,
-  run_id TEXT,
-  state TEXT NOT NULL,
-  result_json TEXT,
-  kind TEXT NOT NULL DEFAULT 'invoke',
-  result_stage_id TEXT,
-  created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
-);
-CREATE INDEX IF NOT EXISTS a2a_tasks_context ON a2a_tasks(context_id);
-CREATE INDEX IF NOT EXISTS a2a_tasks_caller ON a2a_tasks(caller_id);
-
-CREATE TABLE IF NOT EXISTS a2a_messages (
-  caller_id TEXT NOT NULL,
-  message_id TEXT NOT NULL,
-  task_id TEXT NOT NULL,
-  operation TEXT NOT NULL,
-  request_hash TEXT NOT NULL,
-  outcome_json TEXT,
-  created_at TEXT NOT NULL,
-  PRIMARY KEY (caller_id, message_id)
-);
-
-CREATE TABLE IF NOT EXISTS a2a_artifacts (
-  artifact_id TEXT PRIMARY KEY,
-  task_id TEXT NOT NULL,
-  name TEXT NOT NULL,
-  media_type TEXT,
-  size INTEGER NOT NULL,
-  content_path TEXT NOT NULL,
-  hash TEXT NOT NULL,
-  created_at TEXT NOT NULL
-);
-CREATE INDEX IF NOT EXISTS a2a_artifacts_task ON a2a_artifacts(task_id);
-`;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -60,26 +11,15 @@ export class A2aStore {
     artifactsRoot;
     ownsConnection;
     /**
-     * `connection`, when passed, is the SqliteRunStore's own connection to the same `state.db` file
-     * (see `createRunStoreWithConnection`) so the two stores share one transaction domain. Falls
-     * back to opening its own connection when no shared one is available (e.g. a caller-supplied
-     * non-SQLite `RunStore` in bootstrap).
+     * Uses the SqliteRunStore connection to the same `state.db` file so the two stores share one
+     * transaction domain. The Host must open the run store in migrate mode before constructing
+     * A2aStore. Additive `kind` / `result_stage_id` columns for run_stage are applied here.
      */
     constructor(rootDir, connection) {
-        const storeRoot = storeRootFor(rootDir);
-        if (connection) {
-            this.db = connection;
-            this.ownsConnection = false;
-        }
-        else {
-            this.db = new Database(path.join(storeRoot, "state.db"));
-            this.db.pragma("journal_mode = WAL");
-            this.db.pragma("busy_timeout = 5000");
-            this.ownsConnection = true;
-        }
-        this.db.exec(SCHEMA_SQL);
+        this.db = connection;
+        this.ownsConnection = false;
         this.migrateAddStandaloneColumns();
-        this.artifactsRoot = path.join(storeRoot, "a2a-artifacts");
+        this.artifactsRoot = path.join(resolveStoreRoot(rootDir), "a2a-artifacts");
     }
     /**
      * Additive migration for a `state.db` created before the run_stage A2A
@@ -242,4 +182,21 @@ export class A2aStore {
         const removedMessages = this.db.prepare("DELETE FROM a2a_messages WHERE created_at < ?").run(messageCutoff).changes;
         return { removedTasks: expiredTasks.length, removedMessages };
     }
+    /** Deletes every A2A task (and frozen artifact files) bound to a Stageflow run. */
+    async deleteByRunId(runId) {
+        const tasks = this.db
+            .prepare("SELECT task_id FROM a2a_tasks WHERE run_id = ?")
+            .all(runId);
+        for (const { task_id: taskId } of tasks) {
+            for (const artifact of this.listArtifacts(taskId)) {
+                await unlink(artifact.content_path).catch(() => undefined);
+            }
+            this.db.transaction(() => {
+                this.db.prepare("DELETE FROM a2a_artifacts WHERE task_id = ?").run(taskId);
+                this.db.prepare("DELETE FROM a2a_messages WHERE task_id = ?").run(taskId);
+                this.db.prepare("DELETE FROM a2a_tasks WHERE task_id = ?").run(taskId);
+            })();
+        }
+        return { removedTasks: tasks.length };
+    }
 }

package/dist/agent/activity.d.ts

@@ -71,6 +71,9 @@ export type StageLifecycleEvent = {
     event: "failed";
     reason: string;
     usage?: StageUsage;
+} | {
+    event: "interrupted";
+    reason: string;
 } | {
     event: "skipped";
 }

package/dist/agent/bootProviderConfig.d.ts

@@ -0,0 +1,21 @@
+import { type ProviderAuthContext } from "./providerAuth.js";
+export type BootProviderResult = {
+    configured: string[];
+    failures: Array<{
+        providerId: string;
+        code: string;
+        message: string;
+    }>;
+};
+export type BootProviderOptions = {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    requireProviders?: string[];
+    authContext?: ProviderAuthContext;
+    logError?: (message: string) => void;
+};
+/**
+ * Configure providers from STAGEFLOW_PROVIDER_<ID>_API_KEY / _FILE at Host boot.
+ * Soft-fails unreadable/rejected keys by default; requireProviders makes missing ids fatal.
+ */
+export declare function bootProviderConfig(options: BootProviderOptions): Promise<BootProviderResult>;

package/dist/agent/bootProviderConfig.js

@@ -0,0 +1,74 @@
+import { loginWithApiKey, } from "./providerAuth.js";
+import { readSecretFromEnvOrFile, SecretFromEnvError, } from "../config/secretFromEnvOrFile.js";
+const PROVIDER_KEY_RE = /^STAGEFLOW_PROVIDER_([A-Za-z0-9_]+)_API_KEY$/;
+const PROVIDER_FILE_RE = /^STAGEFLOW_PROVIDER_([A-Za-z0-9_]+)_API_KEY_FILE$/;
+function discoverProviders(env) {
+    const byLower = new Map();
+    for (const key of Object.keys(env)) {
+        let envId;
+        const plain = key.match(PROVIDER_KEY_RE);
+        if (plain)
+            envId = plain[1];
+        else {
+            const file = key.match(PROVIDER_FILE_RE);
+            if (file)
+                envId = file[1];
+        }
+        if (envId === undefined)
+            continue;
+        const providerId = envId.toLowerCase().replace(/_/g, "-");
+        if (!byLower.has(providerId)) {
+            byLower.set(providerId, { envId, providerId });
+        }
+    }
+    return [...byLower.values()].sort((a, b) => a.providerId.localeCompare(b.providerId));
+}
+/**
+ * Configure providers from STAGEFLOW_PROVIDER_<ID>_API_KEY / _FILE at Host boot.
+ * Soft-fails unreadable/rejected keys by default; requireProviders makes missing ids fatal.
+ */
+export async function bootProviderConfig(options) {
+    const env = options.env ?? process.env;
+    const logError = options.logError ?? ((message) => console.error(message));
+    const configured = [];
+    const failures = [];
+    for (const { envId, providerId } of discoverProviders(env)) {
+        const envName = `STAGEFLOW_PROVIDER_${envId}_API_KEY`;
+        let secret;
+        try {
+            secret = readSecretFromEnvOrFile(env, envName);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (err instanceof SecretFromEnvError &&
+                message.includes("not both")) {
+                throw err;
+            }
+            const code = err instanceof SecretFromEnvError ? err.code : "config_invalid";
+            failures.push({ providerId, code, message });
+            logError(`stageflow: provider ${providerId} boot failed: ${message}`);
+            continue;
+        }
+        if (secret === undefined)
+            continue;
+        try {
+            await loginWithApiKey(options.cwd, providerId, secret, options.authContext);
+            configured.push(providerId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            failures.push({
+                providerId,
+                code: "provider_not_configured",
+                message,
+            });
+            logError(`stageflow: provider ${providerId} boot failed: ${message}`);
+        }
+    }
+    const required = (options.requireProviders ?? []).map((id) => id.toLowerCase());
+    const missing = required.filter((id) => !configured.includes(id));
+    if (missing.length > 0) {
+        throw new Error(`STAGEFLOW_REQUIRE_PROVIDERS: missing configured providers: ${missing.join(", ")}`);
+    }
+    return { configured, failures };
+}

package/dist/agent/piAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type EventBus, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type EventBus, type ExtensionFactory, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
@@ -6,6 +6,14 @@ import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
 import type { StageGateKind } from "../types/stage.js";
 import { type StageUsage } from "../types/usage.js";
+import { STAGEFLOW_PATH_DENIED } from "../runstore/workspaceLayout.js";
+export { STAGEFLOW_PATH_DENIED };
+export declare const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
+export declare function createDurableRootPathDenyExtension(options: {
+    runWorkspaceDir: string;
+    durableRoot: string;
+    checkoutRoot?: string;
+}): ExtensionFactory;
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).

package/dist/agent/piAdapter.js

@@ -49,6 +49,36 @@ import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { durableRootFileToolDenial, STAGEFLOW_PATH_DENIED, } from "../runstore/workspaceLayout.js";
+export { STAGEFLOW_PATH_DENIED };
+export const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
+const PATH_DENY_FILE_TOOLS = new Set(["read", "write", "edit"]);
+export function createDurableRootPathDenyExtension(options) {
+    const { runWorkspaceDir, durableRoot, checkoutRoot } = options;
+    const allowlistedRoots = checkoutRoot !== undefined && checkoutRoot !== ""
+        ? [checkoutRoot]
+        : undefined;
+    return (pi) => {
+        pi.on("tool_call", async (event, ctx) => {
+            if (!PATH_DENY_FILE_TOOLS.has(event.toolName)) {
+                return undefined;
+            }
+            const rawPath = event.input.path;
+            if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+                return undefined;
+            }
+            const candidate = path.isAbsolute(rawPath)
+                ? rawPath
+                : path.resolve(ctx.cwd, rawPath);
+            const reason = await durableRootFileToolDenial(candidate, runWorkspaceDir, durableRoot, allowlistedRoots);
+            if (reason !== undefined) {
+                return { block: true, reason };
+            }
+            return undefined;
+        });
+    };
+}
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
@@ -825,6 +855,19 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             restoreProvider?.();
             return { ok: false, reason };
         };
+        const extensionFactories = [
+            {
+                name: STAGEFLOW_PATH_DENY_EXTENSION_NAME,
+                factory: createDurableRootPathDenyExtension({
+                    runWorkspaceDir: roots.runWorkspaceDir,
+                    durableRoot: globalStageflowHome(),
+                    ...(roots.checkoutRoot !== undefined
+                        ? { checkoutRoot: roots.checkoutRoot }
+                        : {}),
+                }),
+            },
+            ...(attached.extensionFactories ?? []),
+        ];
         const loader = createSealedResourceLoader({
             cwd: roots.cwd,
             agentDir: roots.agentDir,
@@ -834,9 +877,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             ...(input.skillFilePath !== undefined
                 ? { additionalSkillPaths: [input.skillFilePath] }
                 : {}),
-            ...(attached.extensionFactories !== undefined
-                ? { extensionFactories: attached.extensionFactories }
-                : {}),
+            extensionFactories,
             ...(attached.eventBus !== undefined ? { eventBus: attached.eventBus } : {}),
         });
         await loader.reload();
@@ -943,6 +984,13 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         if (resolved.thinkingLevel) {
             session.setThinkingLevel(resolved.thinkingLevel);
         }
+        await input.onResolvedModel?.({
+            stageId: runtimeStageId(input),
+            model: resolved.model.id,
+            ...(resolved.thinkingLevel !== undefined
+                ? { thinkingLevel: resolved.thinkingLevel }
+                : {}),
+        });
         const liveSession = session;
         return {
             session: liveSession,
@@ -1011,6 +1059,13 @@ async function bindStageSession(input, sessionManager, wiring) {
         if (resolved.thinkingLevel) {
             session.setThinkingLevel(resolved.thinkingLevel);
         }
+        await input.onResolvedModel?.({
+            stageId: runtimeStageId(input),
+            model: resolved.model.id,
+            ...(resolved.thinkingLevel !== undefined
+                ? { thinkingLevel: resolved.thinkingLevel }
+                : {}),
+        });
     }
     catch (err) {
         await shutdownSession(session);

package/dist/agent/piIsolatedMcp.d.ts

@@ -1,6 +1,8 @@
 import { type EventBus, type InlineExtension } from "@earendil-works/pi-coding-agent";
 import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 export declare const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
+export declare function jitiFsCacheDir(): string;
+export declare function resetCreateMcpAdapterCacheForTests(): void;
 type IsolatedMcpServerEntry = Record<string, unknown> & {
     lifecycle: "lazy" | "eager";
     directTools: true;