stageflow 0.32.0 → 0.35.0

package/dist/browser/stageBrowserEnv.js

@@ -1,30 +1,70 @@
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { loadHostConfig } from "../config/hostConfig.js";
+import { browserHostForOwner, loadHostConfig } from "../config/hostConfig.js";
 import { stageDir } from "../runstore/paths.js";
 import { safeAudit } from "./auditSink.js";
 import { assertBrowserSitesAllowed } from "./sitePolicy.js";
 import { BROWSER_ENV_FILENAME, BROWSER_POLICY_FILENAME, } from "./browserHost.js";
 import { ensureRunProfileBrowser } from "./anchor.js";
 import { BROWSER_CLOSED_FILENAME, closeBrowserSession, defaultBrowserRunner, writeSessionOwner, } from "./browserTeardown.js";
-import { defaultDisplayProbe, loginPageUrl, noScreenError } from "./humanLogin.js";
+import { loginPageUrl } from "./humanLogin.js";
+import { persistStageHandoff, resolveStageHandoffCapabilities } from "./stageHandoff.js";
 import { ensureStageLoginCheck, OPEN_COMMAND_TIMEOUT_MS } from "./loginCheck.js";
 import { readPersistedBrowserEnv } from "./persistedEnv.js";
+import { createContainerBrowserHost } from "./containerBrowserHost.js";
+import { createDockerSandboxOrchestrator } from "./dockerSandboxOrchestrator.js";
+import { createVolumeProfileStore } from "./volumeProfileStore.js";
 import { createLocalBrowserHost } from "./localBrowserHost.js";
 import { createLocalProfileStore } from "./localProfileStore.js";
-import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
+import { localOwnerScope } from "./ownerScope.js";
 export { BROWSER_ENV_FILENAME };
 export async function readStagePersistedBrowserEnv(runDir, stageId) {
     return readPersistedBrowserEnv(path.join(stageDir(runDir, stageId), BROWSER_ENV_FILENAME));
 }
 let defaultSupport;
-export function defaultStageBrowserSupport() {
-    defaultSupport ??= {
-        host: createLocalBrowserHost(),
+export function hostLaunchOptions() {
+    const config = loadHostConfig();
+    return {
+        launchArgs: config.browserLaunchArgs,
+        ...(config.browserExecutablePath !== undefined
+            ? { executablePath: config.browserExecutablePath }
+            : {}),
+    };
+}
+function configuredBrowserSupport(liveView) {
+    const config = loadHostConfig();
+    if (browserHostForOwner(config, localOwnerScope()) === "container") {
+        const container = config.browserContainer;
+        return {
+            host: createContainerBrowserHost({
+                orchestrator: createDockerSandboxOrchestrator({
+                    image: container.image,
+                    shmSize: container.shmSize,
+                    memory: container.memory,
+                    pidsLimit: container.pidsLimit,
+                    user: "1000:1000",
+                }),
+                liveView,
+                local: hostLaunchOptions(),
+            }),
+            profiles: createVolumeProfileStore(),
+        };
+    }
+    return {
+        host: createLocalBrowserHost({ liveView, ...hostLaunchOptions() }),
         profiles: createLocalProfileStore(),
     };
+}
+export function defaultStageBrowserSupport() {
+    defaultSupport ??= configuredBrowserSupport("none");
     return defaultSupport;
 }
+let consoleSupport;
+/** Browser support for a process that serves the live view routes (`sf ui`, `sf mcp`). */
+export function consoleStageBrowserSupport() {
+    consoleSupport ??= configuredBrowserSupport("relay");
+    return consoleSupport;
+}
 /**
  * Computed once per stage and persisted in the run dir: agent-browser silently
  * relaunches the browser when a command's launch env differs from the daemon's,
@@ -34,11 +74,9 @@ export async function resolveStageBrowserEnv(support, input) {
     const { browser } = input;
     if (browser === undefined)
         return undefined;
-    if (input.humanLogin === true) {
-        const screen = (support.display ?? defaultDisplayProbe)();
-        if (!screen.hasDisplay)
-            throw noScreenError(screen.docker);
-    }
+    const capabilities = resolveStageHandoffCapabilities(support, {
+        ...(input.humanLogin === true ? { humanLogin: true } : {}),
+    });
     if ((browser.allow_domains?.length ?? 0) > 0 ||
         browser.check !== undefined ||
         browser.login_url !== undefined) {
@@ -46,10 +84,11 @@ export async function resolveStageBrowserEnv(support, input) {
     }
     const dir = stageDir(input.runDir, input.stageId);
     const file = path.join(dir, BROWSER_ENV_FILENAME);
-    // TODO(multi-tenant): open the profile in the run owner's scope, not the fixed local scope.
+    await mkdir(dir, { recursive: true });
+    await persistStageHandoff({ runDir: input.runDir, stageId: input.stageId }, capabilities);
     const profile = browser.profile !== undefined
         ? await support.profiles.open({
-            scope: LOCAL_BROWSER_SCOPE,
+            scope: input.scope,
             name: browser.profile,
         })
         : undefined;
@@ -97,10 +136,9 @@ export async function resolveStageBrowserEnv(support, input) {
     if (persisted === undefined) {
         await writeEnv(fresh);
         if (browser.profile !== undefined) {
-            // TODO(multi-tenant): audit the run owner's scope.
             await safeAudit(support.audit, {
                 event: "profile_used",
-                scope: LOCAL_BROWSER_SCOPE,
+                scope: input.scope,
                 profile: browser.profile,
                 runId: input.runId,
                 stageId: input.stageId,

package/dist/browser/stageHandoff.d.ts

@@ -0,0 +1,47 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+import type { StageBrowserSupport } from "./browserHost.js";
+import { type GateHandoff, type HostGateContext } from "./gateHandoff.js";
+import { type BrowserHostCapabilities } from "./hostCapabilities.js";
+/** The slice of the host capability record a stage's handoff depends on; persisted per stage. */
+export type StageHandoffCapabilities = Pick<BrowserHostCapabilities, "display" | "liveView">;
+type HandoffInput = {
+    runDir: string;
+    runId: string;
+    stageId: string;
+};
+/**
+ * Probes the display, applies the host's capabilities, and rejects a human-login
+ * stage that has neither a screen nor a live view. Pure of disk writes.
+ */
+export declare function resolveStageHandoffCapabilities(support: StageBrowserSupport, options?: {
+    humanLogin?: boolean;
+}): StageHandoffCapabilities;
+export declare function persistStageHandoff(input: {
+    runDir: string;
+    stageId: string;
+}, capabilities: StageHandoffCapabilities): Promise<void>;
+/** Persisted capabilities of a stage; undefined when none were recorded (older runs, direct stage runs). */
+export declare function readStageHandoff(input: {
+    runDir: string;
+    stageId: string;
+}): Promise<StageHandoffCapabilities | undefined>;
+export declare function gateHandoffFor(context: {
+    runId: string;
+    stageId: string;
+    capabilities: StageHandoffCapabilities;
+}): GateHandoff | undefined;
+/** What the Host stamps on every gate of a browser stage; the agent cannot supply it. */
+export declare function hostGateContextFor(browser: StageBrowserConfig | undefined, context: {
+    runId: string;
+    stageId: string;
+    capabilities: StageHandoffCapabilities;
+}): HostGateContext | undefined;
+/** The handoff for a stage's gates and login prompt. `dirStageId` is the manifest id when it differs from the gate's stage id. */
+export declare function stageGateHandoff(input: HandoffInput & {
+    dirStageId?: string;
+}): Promise<GateHandoff | undefined>;
+/** Host-owned gate fields for a stage; undefined for a stage without a browser. */
+export declare function stageGateContext(input: HandoffInput & {
+    browser: StageBrowserConfig | undefined;
+}): Promise<HostGateContext | undefined>;
+export {};

package/dist/browser/stageHandoff.js

@@ -0,0 +1,101 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stageDir } from "../runstore/paths.js";
+import { browserSite, } from "./gateHandoff.js";
+import { resolveBrowserHostCapabilities, } from "./hostCapabilities.js";
+import { defaultDisplayProbe, noScreenError } from "./humanLogin.js";
+const BROWSER_CAPABILITIES_FILENAME = "browser-capabilities.json";
+/**
+ * Probes the display, applies the host's capabilities, and rejects a human-login
+ * stage that has neither a screen nor a live view. Pure of disk writes.
+ */
+export function resolveStageHandoffCapabilities(support, options = {}) {
+    const capabilities = resolveBrowserHostCapabilities(support.host.capabilities);
+    const probe = support.display ?? defaultDisplayProbe;
+    if (support.host.capabilities === undefined) {
+        capabilities.display = probe().hasDisplay ? "local_window" : "headless_only";
+    }
+    else if (capabilities.display === "local_window" && support.display !== undefined && !support.display().hasDisplay) {
+        capabilities.display = "headless_only";
+    }
+    if (options.humanLogin === true &&
+        capabilities.display === "headless_only" &&
+        capabilities.liveView === "none") {
+        throw noScreenError(probe().docker);
+    }
+    if (options.humanLogin === true &&
+        capabilities.display !== "local_window" &&
+        capabilities.viewerInput === "view_only") {
+        throw new Error("A human login stage needs an interactive live view, but this browser host offers a view-only one (missing capability viewer_input: interactive).");
+    }
+    return { display: capabilities.display, liveView: capabilities.liveView };
+}
+export async function persistStageHandoff(input, capabilities) {
+    const dir = stageDir(input.runDir, input.stageId);
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, BROWSER_CAPABILITIES_FILENAME), `${JSON.stringify({ display: capabilities.display, liveView: capabilities.liveView })}\n`, { mode: 0o600 });
+}
+/** Persisted capabilities of a stage; undefined when none were recorded (older runs, direct stage runs). */
+export async function readStageHandoff(input) {
+    const file = path.join(stageDir(input.runDir, input.stageId), BROWSER_CAPABILITIES_FILENAME);
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const { display, liveView } = resolveBrowserHostCapabilities(parsed);
+            return { display, liveView };
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return undefined;
+}
+export function gateHandoffFor(context) {
+    const { capabilities } = context;
+    if (capabilities.display === "local_window")
+        return { kind: "local_window" };
+    if (capabilities.liveView !== "none") {
+        return {
+            kind: "live_view",
+            url: `/api/runs/${encodeURIComponent(context.runId)}/stages/${encodeURIComponent(context.stageId)}/live-view`,
+        };
+    }
+    return undefined;
+}
+/** What the Host stamps on every gate of a browser stage; the agent cannot supply it. */
+export function hostGateContextFor(browser, context) {
+    if (browser === undefined)
+        return undefined;
+    const site = browserSite(browser);
+    const handoff = gateHandoffFor(context);
+    return {
+        ...(handoff !== undefined ? { handoff } : {}),
+        ...(site !== undefined ? { site } : {}),
+        ...(browser.profile !== undefined ? { profile: browser.profile } : {}),
+    };
+}
+// No record (older runs, direct stage runs) keeps its historical meaning: a local window.
+const LEGACY_CAPABILITIES = { display: "local_window", liveView: "none" };
+async function capabilitiesOf(input) {
+    return ((await readStageHandoff({ runDir: input.runDir, stageId: input.dirStageId ?? input.stageId })) ??
+        LEGACY_CAPABILITIES);
+}
+/** The handoff for a stage's gates and login prompt. `dirStageId` is the manifest id when it differs from the gate's stage id. */
+export async function stageGateHandoff(input) {
+    return gateHandoffFor({
+        runId: input.runId,
+        stageId: input.stageId,
+        capabilities: await capabilitiesOf(input),
+    });
+}
+/** Host-owned gate fields for a stage; undefined for a stage without a browser. */
+export async function stageGateContext(input) {
+    if (input.browser === undefined)
+        return undefined;
+    return hostGateContextFor(input.browser, {
+        runId: input.runId,
+        stageId: input.stageId,
+        capabilities: await capabilitiesOf(input),
+    });
+}

package/dist/browser/stageProfileLock.d.ts

@@ -2,6 +2,7 @@ import type { StageBrowserSupport } from "./browserHost.js";
 import type { ProfileLock, ProfileLockOwner, RunLiveness } from "./profileLock.js";
 export declare function stageProfileLock(support: StageBrowserSupport): ProfileLock;
 export type ProfileWaitInput = {
+    scope: string;
     profile: string;
     owner: ProfileLockOwner;
     isRunLive?: RunLiveness;

package/dist/browser/stageProfileLock.js

@@ -1,5 +1,4 @@
 import { createLocalProfileLock } from "./localProfileLock.js";
-import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
 const DEFAULT_LOCK_POLL_MS = 250;
 let defaultLock;
 export function stageProfileLock(support) {
@@ -14,8 +13,7 @@ export function stageProfileLock(support) {
  */
 export async function acquireStageProfile(support, input) {
     const locks = stageProfileLock(support);
-    // TODO(multi-tenant): take the scope from the run owner instead of the fixed local scope.
-    const key = { scope: LOCAL_BROWSER_SCOPE, name: input.profile };
+    const key = { scope: input.scope, name: input.profile };
     const pollMs = support.lockPollMs ?? DEFAULT_LOCK_POLL_MS;
     let announced;
     for (;;) {

package/dist/browser/volumeProfileStore.d.ts

@@ -0,0 +1,7 @@
+import { type ProfileStore } from "./profileStore.js";
+/**
+ * Profiles that live in a volume the sandbox orchestrator provisions. The handle
+ * carries a reference, never a folder; creating, sizing and removing the volume
+ * belong to the orchestrator, so `delete` only forgets the reference.
+ */
+export declare function createVolumeProfileStore(): ProfileStore;

package/dist/browser/volumeProfileStore.js

@@ -0,0 +1,35 @@
+import { validateProfileKey, validateProfileScope, } from "./profileStore.js";
+/**
+ * Profiles that live in a volume the sandbox orchestrator provisions. The handle
+ * carries a reference, never a folder; creating, sizing and removing the volume
+ * belong to the orchestrator, so `delete` only forgets the reference.
+ */
+export function createVolumeProfileStore() {
+    const scopes = new Map();
+    return {
+        async open(rawKey) {
+            const key = validateProfileKey(rawKey);
+            let profiles = scopes.get(key.scope);
+            if (!profiles) {
+                profiles = new Map();
+                scopes.set(key.scope, profiles);
+            }
+            let handle = profiles.get(key.name);
+            if (!handle) {
+                handle = { key, volumeRef: `${key.scope}/${key.name}` };
+                profiles.set(key.name, handle);
+            }
+            return handle;
+        },
+        async list(scope) {
+            return [...(scopes.get(validateProfileScope(scope))?.keys() ?? [])].sort();
+        },
+        async delete(rawKey) {
+            const key = validateProfileKey(rawKey);
+            scopes.get(key.scope)?.delete(key.name);
+        },
+        async deleteScope(scope) {
+            scopes.delete(validateProfileScope(scope));
+        },
+    };
+}

package/dist/cli/browserCommand.d.ts

@@ -16,6 +16,8 @@ export declare const BROWSER_EXIT: {
 export type BrowserCommandDeps = {
     log: (line: string) => void;
     error: (line: string) => void;
+    /** Owner scope of the command; the CLI runs as the local owner when unset. */
+    scope?: string;
     store: ProfileStore;
     host: BrowserHost;
     locks: ProfileLock;
@@ -29,7 +31,7 @@ export type BrowserCommandDeps = {
     /** True when a daemon session for this env is open. */
     sessionOpen: (env: BrowserEnv) => boolean;
     /** profile name -> ISO time of last recorded use (from the audit log). */
-    auditLastUsed: () => Promise<Record<string, string>>;
+    auditLastUsed: (scope: string) => Promise<Record<string, string>>;
     confirm: (question: string) => Promise<boolean>;
     interactive: boolean;
     signal?: AbortSignal;

package/dist/cli/browserCommand.js

@@ -6,13 +6,13 @@ import { createInterface } from "node:readline";
 import { localAuditLogPath } from "../browser/auditSink.js";
 import { closeBrowserSession, defaultBrowserRunner } from "../browser/browserTeardown.js";
 import { defaultDisplayProbe, noScreenError } from "../browser/humanLogin.js";
+import { hostLaunchOptions } from "../browser/stageBrowserEnv.js";
 import { createLocalBrowserHost } from "../browser/localBrowserHost.js";
 import { createLocalProfileLock } from "../browser/localProfileLock.js";
 import { createLocalProfileStore } from "../browser/localProfileStore.js";
 import { matchLoginState, runLoginCheck } from "../browser/loginCheck.js";
-// TODO(multi-tenant): every `sf browser` command below uses the fixed local scope.
-// In a hosted service the scope must come from the signed-in user. Search for LOCAL_BROWSER_SCOPE in this file.
-import { InvalidProfileKeyError, LOCAL_BROWSER_SCOPE, validateProfileName, } from "../browser/profileStore.js";
+import { localOwnerScope } from "../browser/ownerScope.js";
+import { InvalidProfileKeyError, validateProfileName, } from "../browser/profileStore.js";
 import { cliRunLive, createRunLiveness } from "../browser/runLiveness.js";
 import { loadHostConfig } from "../config/hostConfig.js";
 import { BlockedSiteError, hostOf, isBlockedHost } from "../browser/sitePolicy.js";
@@ -41,6 +41,9 @@ const DEFAULT_LOGIN_TIMEOUT_SEC = 300;
 const LOGIN_POLL_MS = 1000;
 const LOGIN_CLOSED_AFTER_FAILED_READS = 3;
 const STAGE_ID = "browser-cli";
+function scopeOf(deps) {
+    return deps.scope ?? localOwnerScope();
+}
 class CliError extends Error {
     code;
     exit;
@@ -88,7 +91,7 @@ function defaultSessionOpen(env) {
         return false;
     }
 }
-async function defaultAuditLastUsed() {
+async function defaultAuditLastUsed(scope) {
     const out = {};
     let text;
     try {
@@ -103,7 +106,7 @@ async function defaultAuditLastUsed() {
         try {
             const rec = JSON.parse(line);
             if (rec.event === "profile_used" &&
-                rec.scope === LOCAL_BROWSER_SCOPE &&
+                rec.scope === scope &&
                 typeof rec.profile === "string" &&
                 typeof rec.at === "string" &&
                 (out[rec.profile] === undefined || rec.at > out[rec.profile])) {
@@ -132,7 +135,7 @@ function defaultDeps() {
         log: (line) => console.log(line),
         error: (line) => console.error(line),
         store: createLocalProfileStore(),
-        host: createLocalBrowserHost(),
+        host: createLocalBrowserHost(hostLaunchOptions()),
         locks: createLocalProfileLock({ isRunLive }),
         runner: defaultBrowserRunner,
         display: () => defaultDisplayProbe(),
@@ -201,17 +204,17 @@ function newOwner() {
     return { runId: `cli-${process.pid}-${randomBytes(4).toString("hex")}`, stageId: STAGE_ID };
 }
 async function withProfile(deps, name, fn, options) {
-    const names = await deps.store.list(LOCAL_BROWSER_SCOPE);
+    const names = await deps.store.list(scopeOf(deps));
     if (!options.create && !names.includes(name)) {
         throw new CliError(`Profile "${name}" does not exist. Create it with sf browser login.`, "not_found", BROWSER_EXIT.error);
     }
     const owner = newOwner();
-    const got = await deps.locks.acquire({ scope: LOCAL_BROWSER_SCOPE, name }, owner);
+    const got = await deps.locks.acquire({ scope: scopeOf(deps), name }, owner);
     if (got.status === "queued") {
         throw new CliError(`Profile "${name}" is in use by run ${got.holder.runId}${got.holder.stageId !== undefined ? ` stage ${got.holder.stageId}` : ""}. Try again when it finishes.`, "profile_busy", BROWSER_EXIT.busy);
     }
     try {
-        const handle = await deps.store.open({ scope: LOCAL_BROWSER_SCOPE, name });
+        const handle = await deps.store.open({ scope: scopeOf(deps), name });
         return await fn(handle);
     }
     finally {
@@ -240,16 +243,18 @@ function closeOpts(deps) {
     };
 }
 async function profilesCmd(deps, p) {
-    const names = await deps.store.list(LOCAL_BROWSER_SCOPE);
-    const audited = await deps.auditLastUsed().catch(() => ({}));
+    const names = await deps.store.list(scopeOf(deps));
+    const audited = await deps.auditLastUsed(scopeOf(deps)).catch(() => ({}));
     const profiles = [];
     for (const name of names) {
         let last = audited[name];
         try {
-            const handle = await deps.store.open({ scope: LOCAL_BROWSER_SCOPE, name });
-            const iso = (await stat(handle.profileDir)).mtime.toISOString();
-            if (last === undefined || iso > last)
-                last = iso;
+            const handle = await deps.store.open({ scope: scopeOf(deps), name });
+            if (handle.profileDir !== undefined) {
+                const iso = (await stat(handle.profileDir)).mtime.toISOString();
+                if (last === undefined || iso > last)
+                    last = iso;
+            }
         }
         catch {
             // store without a real folder
@@ -263,9 +268,9 @@ async function profilesCmd(deps, p) {
 }
 async function statusCmd(deps, p) {
     const name = requireName(p);
-    const exists = (await deps.store.list(LOCAL_BROWSER_SCOPE)).includes(name);
+    const exists = (await deps.store.list(scopeOf(deps))).includes(name);
     let lock = null;
-    const holder = await deps.locks.holder({ scope: LOCAL_BROWSER_SCOPE, name });
+    const holder = await deps.locks.holder({ scope: scopeOf(deps), name });
     if (holder !== undefined) {
         lock = {
             run_id: holder.runId,
@@ -275,7 +280,7 @@ async function statusCmd(deps, p) {
     }
     let sessionOpen = false;
     if (exists) {
-        const handle = await deps.store.open({ scope: LOCAL_BROWSER_SCOPE, name });
+        const handle = await deps.store.open({ scope: scopeOf(deps), name });
         sessionOpen = deps.sessionOpen(await envFor(deps, handle, { profile: name }));
     }
     const doc = { name, exists, locked: lock !== null, lock, session_open: sessionOpen };
@@ -403,7 +408,7 @@ async function loginCmd(deps, p) {
 }
 async function clearCmd(deps, p) {
     const name = requireName(p);
-    if (!(await deps.store.list(LOCAL_BROWSER_SCOPE)).includes(name)) {
+    if (!(await deps.store.list(scopeOf(deps))).includes(name)) {
         throw new CliError(`Profile "${name}" does not exist.`, "not_found", BROWSER_EXIT.error);
     }
     if (!p.yes) {
@@ -418,7 +423,7 @@ async function clearCmd(deps, p) {
     return withProfile(deps, name, async (handle) => {
         const env = await envFor(deps, handle, { profile: name });
         await closeBrowserSession(env, closeOpts(deps)).catch(() => undefined);
-        await deps.store.delete({ scope: LOCAL_BROWSER_SCOPE, name });
+        await deps.store.delete({ scope: scopeOf(deps), name });
         emit(deps, p.json, { cleared: true, name }, [`Cleared profile "${name}".`]);
         return BROWSER_EXIT.ok;
     }, { create: false });

package/dist/cli/resolveCliProjectRoot.d.ts

@@ -0,0 +1,7 @@
+import type { RunStore } from "../runstore/port.js";
+export type ResolvedCliProjectRoot = {
+    rootPath: string;
+    wireId: string;
+};
+export declare function resolveCliProjectRootLocal(flag: string): ResolvedCliProjectRoot | null;
+export declare function resolveCliProjectRoot(flag: string, store: RunStore): Promise<ResolvedCliProjectRoot>;

package/dist/cli/resolveCliProjectRoot.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+import { findCatalogRoot, resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
+import { WORKSPACE_CATALOG_ID, workspaceCatalogPath, } from "../project/workspaceCatalog.js";
+export function resolveCliProjectRootLocal(flag) {
+    const trimmed = flag.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (trimmed === WORKSPACE_CATALOG_ID) {
+        return { rootPath: workspaceCatalogPath(), wireId: WORKSPACE_CATALOG_ID };
+    }
+    if (path.isAbsolute(trimmed)) {
+        const resolved = path.resolve(trimmed);
+        return { rootPath: resolved, wireId: resolved };
+    }
+    return null;
+}
+export async function resolveCliProjectRoot(flag, store) {
+    const local = resolveCliProjectRootLocal(flag);
+    if (local)
+        return local;
+    const roots = await resolveCatalogRoots({ store });
+    const found = findCatalogRoot(roots, flag.trim());
+    if (found === undefined) {
+        throw new Error(`Unknown project_root: ${flag.trim()}`);
+    }
+    return { rootPath: found.path, wireId: found.project_root };
+}

package/dist/cli/runCommand.d.ts

@@ -3,7 +3,7 @@ import type { StartRunResult } from "../runtime/runManager.js";
 import type { TaskFile } from "../types/task.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
 import { type CliRunReportIo } from "./runOutput.js";
-export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
+export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--project-root <id-or-path>] [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
 export type RunCommandIo = CliRunReportIo;
 export type StartRunFn = (input: {
     task: string | TaskFile;