stageflow 0.19.0 → 0.25.0

package/dist/a2a/store.js

@@ -0,0 +1,245 @@
+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 { 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();
+}
+export class A2aStore {
+    db;
+    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).
+     */
+    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.migrateAddStandaloneColumns();
+        this.artifactsRoot = path.join(storeRoot, "a2a-artifacts");
+    }
+    /**
+     * Additive migration for a `state.db` created before the run_stage A2A
+     * operation existed: `CREATE TABLE IF NOT EXISTS` above never alters an
+     * already-existing a2a_tasks table, so a pre-existing one is missing these
+     * two columns. Same PRAGMA table_info-guarded ADD COLUMN pattern as
+     * src/runstore/sqlite/SqliteRunStore.ts.
+     */
+    migrateAddStandaloneColumns() {
+        const cols = this.db.prepare(`PRAGMA table_info(a2a_tasks)`).all();
+        if (!cols.some((c) => c.name === "kind")) {
+            this.db.exec(`ALTER TABLE a2a_tasks ADD COLUMN kind TEXT NOT NULL DEFAULT 'invoke'`);
+        }
+        if (!cols.some((c) => c.name === "result_stage_id")) {
+            this.db.exec(`ALTER TABLE a2a_tasks ADD COLUMN result_stage_id TEXT`);
+        }
+    }
+    close() {
+        if (this.ownsConnection)
+            this.db.close();
+    }
+    ensureContext(callerId, contextId) {
+        if (contextId) {
+            const row = this.db
+                .prepare("SELECT caller_id FROM a2a_contexts WHERE context_id = ?")
+                .get(contextId);
+            if (row && row.caller_id !== callerId) {
+                throw new Error("Context belongs to a different caller");
+            }
+            if (row)
+                return contextId;
+            this.db
+                .prepare("INSERT INTO a2a_contexts (context_id, caller_id, created_at) VALUES (?, ?, ?)")
+                .run(contextId, callerId, nowIso());
+            return contextId;
+        }
+        const generated = randomUUID();
+        this.db
+            .prepare("INSERT INTO a2a_contexts (context_id, caller_id, created_at) VALUES (?, ?, ?)")
+            .run(generated, callerId, nowIso());
+        return generated;
+    }
+    getMessage(callerId, messageId) {
+        const row = this.db
+            .prepare("SELECT task_id AS taskId, request_hash AS requestHash, outcome_json AS outcomeJson FROM a2a_messages WHERE caller_id = ? AND message_id = ?")
+            .get(callerId, messageId);
+        if (!row)
+            return undefined;
+        return { taskId: row.taskId, requestHash: row.requestHash, outcome: row.outcomeJson ? JSON.parse(row.outcomeJson) : undefined };
+    }
+    recordMessage(params) {
+        this.db
+            .prepare("INSERT INTO a2a_messages (caller_id, message_id, task_id, operation, request_hash, outcome_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)")
+            .run(params.callerId, params.messageId, params.taskId, params.operation, params.requestHash, JSON.stringify(params.outcome), nowIso());
+    }
+    getTaskBySubmissionKey(key) {
+        return this.db.prepare("SELECT * FROM a2a_tasks WHERE submission_key = ?").get(key);
+    }
+    createTask(params) {
+        const at = nowIso();
+        this.db
+            .prepare(`INSERT INTO a2a_tasks
+          (task_id, context_id, caller_id, publication_id, publication_revision, submission_key, run_id, state, result_json, kind, result_stage_id, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, 'submitted', NULL, ?, ?, ?, ?)`)
+            .run(params.taskId, params.contextId, params.callerId, params.publicationId, params.publicationRevision, params.submissionKey, params.runId, params.kind ?? "invoke", params.resultStageId ?? null, at, at);
+        return this.getTask(params.taskId);
+    }
+    getTask(taskId) {
+        return this.db.prepare("SELECT * FROM a2a_tasks WHERE task_id = ?").get(taskId);
+    }
+    listTasksForCaller(callerId, contextId) {
+        if (contextId) {
+            return this.db
+                .prepare("SELECT * FROM a2a_tasks WHERE caller_id = ? AND context_id = ? ORDER BY created_at ASC")
+                .all(callerId, contextId);
+        }
+        return this.db
+            .prepare("SELECT * FROM a2a_tasks WHERE caller_id = ? ORDER BY created_at ASC")
+            .all(callerId);
+    }
+    getArtifact(taskId, artifactId) {
+        return this.db
+            .prepare("SELECT * FROM a2a_artifacts WHERE task_id = ? AND artifact_id = ?")
+            .get(taskId, artifactId);
+    }
+    listArtifacts(taskId) {
+        return this.db.prepare("SELECT * FROM a2a_artifacts WHERE task_id = ?").all(taskId);
+    }
+    /** Freezes a successful outcome exactly once; a second call for an already-terminal task is a no-op. */
+    async freezeCompleted(taskId, result) {
+        return this.freeze(taskId, "completed", result);
+    }
+    /** Freezes a failure exactly once; a second call for an already-terminal task is a no-op. */
+    async freezeFailed(taskId) {
+        return this.freeze(taskId, "failed", undefined);
+    }
+    async freeze(taskId, state, result) {
+        const current = this.getTask(taskId);
+        if (!current || current.state === "completed" || current.state === "failed")
+            return;
+        const artifactRows = [];
+        if (result) {
+            for (const artifact of result.artifacts) {
+                const artifactId = randomUUID();
+                const hash = createHash("sha256").update(artifact.bytes).digest("hex");
+                const dir = path.join(this.artifactsRoot, taskId);
+                await mkdir(dir, { recursive: true });
+                const contentPath = path.join(dir, artifactId);
+                await writeFile(contentPath, artifact.bytes);
+                artifactRows.push({
+                    artifact_id: artifactId,
+                    task_id: taskId,
+                    name: artifact.name,
+                    media_type: artifact.mediaType ?? null,
+                    size: artifact.bytes.length,
+                    content_path: contentPath,
+                    hash,
+                    created_at: nowIso(),
+                });
+            }
+        }
+        const resultJson = result ? JSON.stringify({ summary: result.summary, payload: result.payload }) : null;
+        const transact = this.db.transaction(() => {
+            const outcome = this.db
+                .prepare("UPDATE a2a_tasks SET state = ?, result_json = ?, updated_at = ? WHERE task_id = ? AND state NOT IN ('completed', 'failed')")
+                .run(state, resultJson, nowIso(), taskId);
+            if (outcome.changes === 0)
+                return;
+            for (const row of artifactRows) {
+                this.db
+                    .prepare("INSERT INTO a2a_artifacts (artifact_id, task_id, name, media_type, size, content_path, hash, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+                    .run(row.artifact_id, row.task_id, row.name, row.media_type, row.size, row.content_path, row.hash, row.created_at);
+            }
+        });
+        transact();
+    }
+    countNonterminal(callerId) {
+        const row = this.db
+            .prepare("SELECT COUNT(*) AS n FROM a2a_tasks WHERE caller_id = ? AND state NOT IN ('completed', 'failed')")
+            .get(callerId);
+        return row.n;
+    }
+    /** Deletes terminal tasks (and their frozen artifact files) and message tombstones older than the retention window. */
+    async pruneExpired(now, terminalRetentionMs = TERMINAL_RETENTION_MS, messageRetentionMs = MESSAGE_TOMBSTONE_RETENTION_MS) {
+        const terminalCutoff = new Date(now.getTime() - terminalRetentionMs).toISOString();
+        const messageCutoff = new Date(now.getTime() - messageRetentionMs).toISOString();
+        const expiredTasks = this.db
+            .prepare("SELECT task_id FROM a2a_tasks WHERE state IN ('completed', 'failed') AND updated_at < ?")
+            .all(terminalCutoff);
+        for (const { task_id: taskId } of expiredTasks) {
+            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);
+            })();
+        }
+        const removedMessages = this.db.prepare("DELETE FROM a2a_messages WHERE created_at < ?").run(messageCutoff).changes;
+        return { removedTasks: expiredTasks.length, removedMessages };
+    }
+}

package/dist/agent/activity.d.ts

@@ -86,6 +86,11 @@ export type StageLifecycleEvent = {
 /** Operator chose to leave the verified failure terminal. */
  | {
     event: "manual_recovery_stopped";
+} | {
+    event: "feedback_loop_decided";
+    decision: "extend" | "continue" | "abandon";
+    loopId: string;
+    reason?: string;
 };
 export type StageLogLine = StageActivityEvent | StageLifecycleEvent;
 export declare function truncateActivityText(value: unknown, limit?: number): string | undefined;

package/dist/agent/activityObserver.d.ts

@@ -1,5 +1,6 @@
 import { type StageActivityEvent } from "./activity.js";
 export declare const TOOL_PROGRESS_THROTTLE_MS = 300;
+export declare const STREAM_FLUSH_THROTTLE_MS = 300;
 export type StageActivityObserver = {
     onAssistantTextDelta(delta: string): void;
     onThinkingDelta(delta: string): void;
@@ -10,6 +11,8 @@ export type StageActivityObserver = {
 };
 export type CreateStageActivityObserverOptions = {
     onActivity?: (event: StageActivityEvent) => void;
+    /** Fired for every non-empty assistant text delta, regardless of writeStderr. */
+    onAssistantTextDelta?: (delta: string) => void;
     writeStderr?: boolean;
     toolProgressThrottleMs?: number;
 };

package/dist/agent/activityObserver.js

@@ -1,5 +1,6 @@
 import { truncateActivityText, } from "./activity.js";
 export const TOOL_PROGRESS_THROTTLE_MS = 300;
+export const STREAM_FLUSH_THROTTLE_MS = 300;
 function writeIndentedPreview(preview) {
     for (const line of preview.split("\n")) {
         process.stderr.write(`    ${line}\n`);
@@ -127,7 +128,11 @@ export function createStageActivityObserver(options = {}) {
     };
     return {
         onAssistantTextDelta(delta) {
-            if (!writeStderr || !delta) {
+            if (!delta) {
+                return;
+            }
+            options.onAssistantTextDelta?.(delta);
+            if (!writeStderr) {
                 return;
             }
             assistantStreamedForMessage = true;

package/dist/agent/piAdapter.js

@@ -371,8 +371,12 @@ export function routeSessionEventToProgress(event, options) {
  * Map Pi session events to StageActivityEvent at the adapter edge, then
  * forward to the activity observer (stderr + onActivity).
  */
-function attachStageProgress(session, onActivity, usage) {
-    const observer = createStageActivityObserver({ onActivity, writeStderr: true });
+function attachStageProgress(session, onActivity, usage, onAssistantTextDelta) {
+    const observer = createStageActivityObserver({
+        onActivity,
+        onAssistantTextDelta,
+        writeStderr: true,
+    });
     const verbose = readActivityVerbose();
     const unsubscribe = session.subscribe((event) => {
         routeSessionEventToProgress(event, {
@@ -1119,7 +1123,7 @@ export class PiAgentAdapter {
                 return;
             }
             session = bound;
-            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage);
+            unsubscribeProgress = attachStageProgress(session, input.onActivity, wiring.usage, input.onAssistantTextDelta);
         })();
         const runWithTimeout = async (work) => {
             await preparePromise;

package/dist/agent/port.d.ts

@@ -60,6 +60,8 @@ export type StageRunInput = {
     sessionMode?: StageSessionMode;
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
+    /** Optional raw assistant-text-delta sink, fired alongside onActivity, not instead of it. */
+    onAssistantTextDelta?: (delta: string) => void;
     skillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
     cloneEmitContext?: CloneEmitContext;

package/dist/agent/providerInspect.d.ts

@@ -0,0 +1,19 @@
+import { type PiHomeDetectResult, type ProviderAuthContext, type ProviderAuthStatus, type ProviderSummary, type ProvidersListResult } from "./providerAuth.js";
+export type ProviderReadinessRow = ProviderSummary & {
+    configured: boolean;
+    authKind?: ProviderAuthStatus["authKind"];
+    source?: string;
+};
+export type ProviderReadinessInspect = {
+    authShell: ProvidersListResult["authShell"];
+    via: ProvidersListResult["via"];
+    detect: PiHomeDetectResult;
+    providers: ProviderReadinessRow[];
+};
+export declare function inspectProviderReadiness(cwd: string, ctx?: ProviderAuthContext): Promise<ProviderReadinessInspect>;
+export declare function mapProviderAuthError(err: unknown): {
+    status: number;
+    body: {
+        error: string;
+    };
+};

package/dist/agent/providerInspect.js

@@ -0,0 +1,35 @@
+import { defaultContext, detectPiHome, getAuthStatus, listProviders, ProviderAuthError, } from "./providerAuth.js";
+function statusList(statuses) {
+    return Array.isArray(statuses) ? statuses : [statuses];
+}
+export async function inspectProviderReadiness(cwd, ctx = defaultContext) {
+    const listed = await listProviders(cwd, ctx);
+    const statuses = statusList(await getAuthStatus(cwd, undefined, ctx));
+    const statusById = new Map(statuses.map((status) => [status.providerId, status]));
+    const detect = detectPiHome(cwd);
+    return {
+        authShell: listed.authShell,
+        via: listed.via,
+        detect,
+        providers: listed.providers.map((provider) => {
+            const status = statusById.get(provider.id);
+            return {
+                ...provider,
+                configured: status?.configured ?? false,
+                ...(status?.authKind !== undefined
+                    ? { authKind: status.authKind }
+                    : {}),
+                ...(status?.source !== undefined ? { source: status.source } : {}),
+            };
+        }),
+    };
+}
+export function mapProviderAuthError(err) {
+    if (err instanceof ProviderAuthError) {
+        return { status: err.status, body: { error: err.message } };
+    }
+    return {
+        status: 500,
+        body: { error: "Provider auth operation failed" },
+    };
+}

package/dist/agent/streamLogRedact.d.ts

@@ -0,0 +1,2 @@
+/** Scrub common secret-shaped substrings before text is persisted or returned. */
+export declare function redactSecrets(text: string): string;

package/dist/agent/streamLogRedact.js

@@ -0,0 +1,13 @@
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+    /\bghp_[A-Za-z0-9]{20,}\b/g,
+    /\b[A-Za-z_]*KEY[A-Za-z_]*\s*[:=]\s*['"]?[A-Za-z0-9+/_-]{16,}['"]?/gi,
+];
+/** Scrub common secret-shaped substrings before text is persisted or returned. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of SECRET_PATTERNS) {
+        out = out.replace(pattern, "[redacted]");
+    }
+    return out;
+}

package/dist/cli/a2aCommand.d.ts

@@ -0,0 +1,8 @@
+export declare const A2A_USAGE = "sf a2a validate [--config <path>]\nsf a2a list [--config <path>]\nsf a2a add-caller <id> [--config <path>] [--token-env <NAME>]\n\nValidate or inspect an A2A publication configuration, or register a new caller.\n--config defaults to <project-root>/a2a.yaml when omitted -- the same file\nSTAGEFLOW_A2A_CONFIG would point at if set. Caller credentials are read from\nthe environment variables named in the configuration; add-caller only writes\nthe caller's id and its token_env name to the file, never a secret value.";
+export declare function runA2aCommand(args: string[], options: {
+    cwd: string;
+    projectRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+    error?: (line: string) => void;
+}): Promise<number>;

package/dist/cli/a2aCommand.js

@@ -0,0 +1,131 @@
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
+import { loadPublicationRegistry } from "../a2a/registry.js";
+import { a2aConfigPathFor, resolveA2aConfigPath } from "../a2a/configDiscovery.js";
+export const A2A_USAGE = `sf a2a validate [--config <path>]
+sf a2a list [--config <path>]
+sf a2a add-caller <id> [--config <path>] [--token-env <NAME>]
+
+Validate or inspect an A2A publication configuration, or register a new caller.
+--config defaults to <project-root>/a2a.yaml when omitted -- the same file
+STAGEFLOW_A2A_CONFIG would point at if set. Caller credentials are read from
+the environment variables named in the configuration; add-caller only writes
+the caller's id and its token_env name to the file, never a secret value.`;
+const SCAFFOLD = { version: 1, callers: [], publications: [] };
+function deriveTokenEnvName(callerId) {
+    const normalized = callerId
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return (normalized || "CALLER") + "_TOKEN";
+}
+function parseFlags(args) {
+    let config;
+    let tokenEnv;
+    const positionals = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === "--config") {
+            config = args[(i += 1)];
+        }
+        else if (args[i] === "--token-env") {
+            tokenEnv = args[(i += 1)];
+        }
+        else {
+            positionals.push(args[i]);
+        }
+    }
+    return { config, tokenEnv, positionals };
+}
+async function addCaller(configPath, callerId, tokenEnvOverride) {
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch {
+        raw = undefined;
+    }
+    const config = raw ? (parse(raw) ?? {}) : { ...SCAFFOLD };
+    if (typeof config !== "object" || Array.isArray(config)) {
+        throw new Error(configPath + " does not contain a YAML mapping");
+    }
+    if (config.version === undefined)
+        config.version = 1;
+    if (config.callers === undefined)
+        config.callers = [];
+    if (config.publications === undefined)
+        config.publications = [];
+    const callers = config.callers;
+    if (!Array.isArray(callers)) {
+        throw new Error('"callers" in ' + configPath + " is not a list");
+    }
+    if (callers.some((entry) => entry && typeof entry === "object" && entry.id === callerId)) {
+        throw new Error('Caller "' + callerId + '" already exists in ' + configPath);
+    }
+    const tokenEnv = tokenEnvOverride ?? deriveTokenEnvName(callerId);
+    callers.push({ id: callerId, token_env: tokenEnv });
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, stringify(config));
+    const token = randomBytes(24).toString("hex");
+    return { tokenEnv, token, created: raw === undefined };
+}
+export async function runA2aCommand(args, options) {
+    const log = options.log ?? console.log;
+    const error = options.error ?? console.error;
+    const env = options.env ?? process.env;
+    const projectRoot = options.projectRoot ?? options.cwd;
+    if (args[0] === "--help" || args[0] === "-h") {
+        log(A2A_USAGE);
+        return 0;
+    }
+    const sub = args[0];
+    if (sub !== "validate" && sub !== "list" && sub !== "add-caller") {
+        error(A2A_USAGE);
+        return 1;
+    }
+    const { config, tokenEnv, positionals } = parseFlags(args.slice(1));
+    if (sub === "add-caller") {
+        if (positionals.length !== 1 || !positionals[0]) {
+            error(A2A_USAGE);
+            return 1;
+        }
+        const configPath = config ? path.resolve(options.cwd, config) : a2aConfigPathFor(projectRoot);
+        try {
+            const result = await addCaller(configPath, positionals[0], tokenEnv);
+            log(JSON.stringify({ ok: true, configPath, callerId: positionals[0], tokenEnv: result.tokenEnv, created: result.created }));
+            log('Generated a token for caller "' + positionals[0] + '". Export it before starting the host (or store it in your secrets manager):');
+            log("  export " + result.tokenEnv + "=" + result.token);
+            if (result.created) {
+                log("Created " + configPath + " with no publications yet -- add at least one under `publications:` before this config can be loaded.");
+            }
+            return 0;
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    if (positionals.length !== 0) {
+        error(A2A_USAGE);
+        return 1;
+    }
+    const configPath = config ? path.resolve(options.cwd, config) : resolveA2aConfigPath(projectRoot, env);
+    if (!configPath) {
+        error("No A2A configuration found. Pass --config <path>, or create " + a2aConfigPathFor(projectRoot) + ".");
+        return 1;
+    }
+    try {
+        const registry = await loadPublicationRegistry(configPath, env);
+        log(JSON.stringify({ ok: true, configPath: registry.configPath, publicUrl: registry.publicUrl, mode: "discovery", publications: registry.summaries() }));
+        if (sub === "list") {
+            log("Configuration validated locally. An already-running host must be restarted explicitly to pick up changes.");
+        }
+        return 0;
+    }
+    catch (err) {
+        error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}

package/dist/cli/artifactCommand.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "node:fs";
 import path from "node:path";
 import { readRunArtifact } from "../mcp/readArtifact.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
 export const ARTIFACT_USAGE = `Usage:
@@ -73,7 +74,6 @@ function resolveSafeOutPath(outPath, cwd) {
 }
 export async function runArtifactCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -99,7 +99,7 @@ export async function runArtifactCommand(args, options = {}) {
         out.error(ARTIFACT_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     try {
         const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
         if (parsed.outPath !== undefined) {

package/dist/cli/envelopeCommand.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { buildHandoffDeliverable, isHandoffSkipped, } from "./handoffFormat.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 export const ENVELOPE_USAGE = `Usage:
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]`;
@@ -198,7 +199,6 @@ function formatHandoffHuman(result) {
 }
 export async function runEnvelopeCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -224,7 +224,7 @@ export async function runEnvelopeCommand(args, options = {}) {
         out.error(ENVELOPE_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     let runContext;
     try {
         runContext = resolveRunContext(parsed, cwd, store);

package/dist/cli/exportRunCommand.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { projectRun } from "../projection/projectRun.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
 export const EXPORT_RUN_USAGE = `Usage:
@@ -94,7 +95,6 @@ function assertRunComplete(status, runId) {
 }
 export async function runExportRunCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -126,7 +126,7 @@ export async function runExportRunCommand(args, options = {}) {
         out.error(EXPORT_RUN_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: projectRoot });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     try {
         const detail = await store.readRun(runId);
         assertRunComplete(detail.status, runId);

package/dist/cli/hostClient.d.ts

@@ -0,0 +1,43 @@
+import type { PipelineRunResult } from "../runtime/pipelineRunner.js";
+import type { AbandonStageResult, DecideFeedbackLoopResult, StartRunResult, StopManualRecoveryResult } from "../runtime/runManager.js";
+import type { DeliverAnswerResult } from "../runtime/stageHitl.js";
+import type { RetryStageResult } from "../runtime/runRetryCoordinator.js";
+import type { RunDetail, RunStore } from "../runstore/port.js";
+export declare function computeRunDir(runId: string): string;
+export declare function httpReadRun(base: string, runId: string): Promise<RunDetail>;
+/** Thin RunStore-shaped reader backed by the global service, for the CLI output helpers that only need `readRun`. */
+export declare function httpStoreReader(base: string): Pick<RunStore, "readRun">;
+export declare function pollRunUntilTerminal(base: string, runId: string, options?: {
+    pollIntervalMs?: number;
+}): Promise<RunDetail>;
+export declare function runDetailToPipelineRunResult(detail: RunDetail): PipelineRunResult;
+export type HttpStartRunInput = {
+    pipeline: string;
+    task: string;
+    checkoutOverride?: string;
+    skipGates?: boolean;
+    gitSha?: string;
+    ciPrUrl?: string;
+    ciJobUrl?: string;
+};
+export declare function httpStartRun(base: string, input: HttpStartRunInput): Promise<StartRunResult>;
+export declare function httpRerun(base: string, runId: string): Promise<StartRunResult>;
+export declare function httpDeliverAnswer(base: string, runId: string, stageId: string, answer: unknown): Promise<DeliverAnswerResult>;
+export declare function httpDecideFeedbackLoop(base: string, runId: string, stageId: string, input: {
+    decision: "extend" | "continue" | "abandon";
+    loopId?: string;
+    reason?: string;
+}): Promise<DecideFeedbackLoopResult>;
+type RetryOrchestrationResult = {
+    ok: true;
+    pipeline: PipelineRunResult;
+} | Extract<RetryStageResult, {
+    ok: false;
+}>;
+export declare function httpRetryStageUntilStop(base: string, runId: string, stageId: string): Promise<RetryOrchestrationResult>;
+export declare function httpResumeTimedOutStage(base: string, runId: string, stageId: string): Promise<RetryStageResult>;
+export declare function httpRecoverManualStageUntilStop(base: string, runId: string, stageId: string, guidance?: string): Promise<RetryOrchestrationResult>;
+export declare function httpStopManualRecovery(base: string, runId: string, stageId: string): Promise<StopManualRecoveryResult>;
+export declare function httpAbandonStage(base: string, runId: string, stageId: string): Promise<AbandonStageResult>;
+export declare function resolveAbsolute(cwd: string, maybeRelative: string): string;
+export {};