stageflow 0.33.0 → 0.36.0

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/doctorCommand.js

@@ -293,7 +293,9 @@ function preflightToDoctorChecks(preflight, strict) {
             ? `toolchain:${c.tool ?? i}`
             : c.kind === "secret"
                 ? `secret:${c.secret ?? i}`
-                : `mcp:${c.server ?? c.stageId ?? i}`;
+                : c.kind === "channel"
+                    ? `channel:${c.connection ?? i}`
+                    : `mcp:${c.server ?? c.stageId ?? i}`;
         let status = "pass";
         if (c.status === "ok") {
             status = "pass";

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;

package/dist/cli/runCommand.js

@@ -2,7 +2,8 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { coerceTaskFile } from "../config/loadTask.js";
-import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
+import { isInsideProjectRoot, relativizeLocalPathForNetwork, } from "../config/catalogRelativePath.js";
+import { resolveCliProjectRootLocal } from "./resolveCliProjectRoot.js";
 import { PipelinePreflightError, PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
 import { httpEnsureProject, httpStartRun, httpStoreReader } from "./hostClient.js";
@@ -10,7 +11,7 @@ import { reportCliRun, writeQueuedAdmissionLine, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_USAGE = `Usage:
-  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>]`;
+  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>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -32,6 +33,7 @@ function parseRunArgs(args) {
     let ciJobUrl;
     let operatorCwd;
     let operatorAgentDir;
+    let projectRoot;
     let json = false;
     let includeStages = false;
     let skipGates = false;
@@ -111,6 +113,13 @@ function parseRunArgs(args) {
             }
             operatorAgentDir = value;
         }
+        else if (arg === "--project-root") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --project-root");
+            }
+            projectRoot = value;
+        }
         else if (arg === "--json") {
             json = true;
         }
@@ -151,8 +160,16 @@ function parseRunArgs(args) {
         ciJobUrl,
         operatorCwd,
         operatorAgentDir,
+        projectRoot,
     };
 }
+function resolvePathUnderCliRoot(rootPath, inputPath, label) {
+    const abs = path.resolve(rootPath, inputPath);
+    if (!isInsideProjectRoot(rootPath, abs)) {
+        throw new Error(`${label} ${abs} is outside project root ${rootPath}`);
+    }
+    return path.relative(rootPath, abs).replace(/\\/g, "/") || ".";
+}
 async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
     const absolute = path.resolve(cwd, taskPath);
     const yamlText = await readFile(absolute, "utf8");
@@ -167,7 +184,7 @@ async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
         task.ref = overrides.ref;
     return task;
 }
-function defaultStartRun(cwd, base, ensureService) {
+function defaultStartRun(cwd, base, ensureService, cliProjectRoot) {
     return async (input) => {
         const ensured = await ensureService();
         if (!ensured.ok) {
@@ -180,20 +197,34 @@ function defaultStartRun(cwd, base, ensureService) {
                     : {}),
             };
         }
-        const pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+        let pipelineRef;
         let task = input.task;
-        let projectRoot = pipelineRef.project_root;
-        if (typeof input.task === "string") {
-            const absTask = path.resolve(cwd, input.task);
-            const cwdAbs = path.resolve(cwd);
-            const relTask = path.relative(cwdAbs, absTask);
-            if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
-                task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+        let projectRoot;
+        if (cliProjectRoot) {
+            pipelineRef = {
+                path: resolvePathUnderCliRoot(cliProjectRoot.rootPath, input.pipeline, "Pipeline"),
+                project_root: cliProjectRoot.wireId,
+            };
+            projectRoot = cliProjectRoot.wireId;
+            if (typeof input.task === "string") {
+                task = resolvePathUnderCliRoot(cliProjectRoot.rootPath, input.task, "Task");
             }
-            else {
-                const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
-                task = taskRef.path;
-                projectRoot = taskRef.project_root;
+        }
+        else {
+            pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+            projectRoot = pipelineRef.project_root;
+            if (typeof input.task === "string") {
+                const absTask = path.resolve(cwd, input.task);
+                const cwdAbs = path.resolve(cwd);
+                const relTask = path.relative(cwdAbs, absTask);
+                if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
+                    task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+                }
+                else {
+                    const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
+                    task = taskRef.path;
+                    projectRoot = taskRef.project_root;
+                }
             }
         }
         const ensuredProject = await httpEnsureProject(base, projectRoot);
@@ -253,8 +284,18 @@ export async function runRunCommand(args, options = {}) {
     if (parsed.operatorCwd !== undefined || parsed.operatorAgentDir !== undefined) {
         out.error("warning: --operator-cwd/--operator-agent-dir have no effect on `sf run` now that pipelines execute in the shared global Stageflow service; set STAGEFLOW_OPERATOR_CWD/STAGEFLOW_OPERATOR_AGENT_DIR before that service first starts instead.");
     }
+    let cliProjectRoot;
+    if (parsed.projectRoot !== undefined) {
+        const local = resolveCliProjectRootLocal(parsed.projectRoot);
+        if (!local) {
+            out.error(`Unknown project_root: ${parsed.projectRoot.trim()}`);
+            out.error(RUN_USAGE);
+            return 1;
+        }
+        cliProjectRoot = local;
+    }
     const startRun = options.startRun ??
-        defaultStartRun(cwd, base, options.ensureService ?? (() => ensureGlobalService()));
+        defaultStartRun(cwd, base, options.ensureService ?? (() => ensureGlobalService()), cliProjectRoot);
     const identity = resolveCiIdentity({
         flags: {
             gitSha: parsed.gitSha,
@@ -266,8 +307,9 @@ export async function runRunCommand(args, options = {}) {
     const store = options.store ?? (parsed.includeStages ? httpStoreReader(base) : undefined);
     try {
         const hasBindingOverride = parsed.repository !== undefined || parsed.ref !== undefined;
+        const taskLoadRoot = cliProjectRoot?.rootPath ?? cwd;
         const taskInput = hasBindingOverride
-            ? await loadTaskWithBindingOverrides(parsed.task, cwd, {
+            ? await loadTaskWithBindingOverrides(parsed.task, taskLoadRoot, {
                 repository: parsed.repository,
                 ref: parsed.ref,
             })

package/dist/cli/skillsCommand.d.ts

@@ -5,6 +5,26 @@ export type SkillsCommandIo = {
     fetch: typeof globalThis.fetch;
     runDoctor: (scriptPath: string, cwd: string) => number;
 };
+export type InstallProjectSkillInput = {
+    projectRoot: string;
+    fromPath?: string;
+    fromZip?: string;
+    zipBytes?: Uint8Array;
+    skillName?: string;
+    checksum?: string;
+    io?: Partial<SkillsCommandIo>;
+};
+export type InstallProjectSkillResult = {
+    ok: true;
+    skillName: string;
+    destPath: string;
+    message: string;
+} | {
+    ok: false;
+    error: string;
+    doctorFailed?: boolean;
+};
+export declare function installProjectSkill(input: InstallProjectSkillInput): Promise<InstallProjectSkillResult>;
 export declare function runSkillsCommand(args: string[], options?: {
     cwd?: string;
     projectRoot?: string;

package/dist/cli/skillsCommand.js

@@ -291,14 +291,18 @@ async function findSkillRootBySkillMd(dir) {
     }
     return undefined;
 }
-async function resolveInstallSource(parsed, io) {
-    const hasPath = parsed.fromPath !== undefined;
-    const hasZip = parsed.fromZip !== undefined;
-    if (hasPath === hasZip) {
-        throw new Error("specify exactly one of --from-path or --from-zip");
-    }
-    if (parsed.fromPath !== undefined) {
-        const sourceRoot = path.resolve(parsed.fromPath);
+async function resolveInstallSource(input, io) {
+    const hasPath = input.fromPath !== undefined;
+    const hasZip = input.fromZip !== undefined;
+    const hasZipBytes = input.zipBytes !== undefined;
+    const sourceCount = Number(hasPath) + Number(hasZip) + Number(hasZipBytes);
+    if (sourceCount !== 1) {
+        throw new Error(hasZipBytes
+            ? "specify exactly one of fromPath, fromZip, or zipBytes"
+            : "specify exactly one of --from-path or --from-zip");
+    }
+    if (input.fromPath !== undefined) {
+        const sourceRoot = path.resolve(input.fromPath);
         try {
             const sourceStat = await stat(sourceRoot);
             if (!sourceStat.isDirectory()) {
@@ -308,13 +312,21 @@ async function resolveInstallSource(parsed, io) {
         catch {
             throw new Error("source path not found");
         }
-        const skillName = parsed.skillName ?? inferSkillNameFromPath(parsed.fromPath);
+        const skillName = input.skillName ?? inferSkillNameFromPath(input.fromPath);
         return { sourceRoot, skillName };
     }
-    const zipRef = parsed.fromZip;
-    const zipBytes = await resolveZipBytes(zipRef, io);
-    if (parsed.checksum !== undefined) {
-        const expected = parseChecksum(parsed.checksum);
+    let zipBytes;
+    let inferredZipName;
+    if (input.zipBytes !== undefined) {
+        zipBytes = Buffer.from(input.zipBytes);
+    }
+    else {
+        const zipRef = input.fromZip;
+        zipBytes = await resolveZipBytes(zipRef, io);
+        inferredZipName = inferSkillNameFromZipRef(zipRef);
+    }
+    if (input.checksum !== undefined) {
+        const expected = parseChecksum(input.checksum);
         const actual = sha256Hex(zipBytes);
         if (actual !== expected) {
             throw new Error("checksum mismatch");
@@ -322,8 +334,9 @@ async function resolveInstallSource(parsed, io) {
     }
     const extractDir = await mkdtemp(path.join(tmpdir(), "sf-skill-zip-"));
     await extractZipBuffer(zipBytes, extractDir);
-    const skillName = parsed.skillName ?? inferSkillNameFromZipRef(zipRef);
-    const sourceRoot = await findSkillRoot(extractDir, skillName);
+    const lookupName = input.skillName ?? inferredZipName ?? "skill";
+    const sourceRoot = await findSkillRoot(extractDir, lookupName);
+    const skillName = input.skillName ?? inferredZipName ?? path.basename(sourceRoot);
     return {
         sourceRoot,
         skillName,
@@ -364,24 +377,46 @@ async function listSkills(projectRoot, io) {
         io.log(`${name}\t${version}\tbin/${name}.mjs`);
     }
 }
-async function installSkill(projectRoot, parsed, io) {
-    const resolved = await resolveInstallSource(parsed, io);
+export async function installProjectSkill(input) {
+    const io = { ...defaultIo, ...input.io };
     try {
-        const destRoot = path.join(skillsDirForRoot(projectRoot), resolved.skillName);
-        await copySkillTree(resolved.sourceRoot, destRoot);
-        const doctorScript = path.join(destRoot, "bin", `${resolved.skillName}.mjs`);
-        const doctorCode = io.runDoctor(doctorScript, projectRoot);
-        if (doctorCode !== 0) {
-            io.error("skill doctor failed");
-            return 1;
+        const resolved = await resolveInstallSource({
+            fromPath: input.fromPath,
+            fromZip: input.fromZip,
+            zipBytes: input.zipBytes,
+            skillName: input.skillName,
+            checksum: input.checksum,
+        }, io);
+        try {
+            const destRoot = path.join(skillsDirForRoot(input.projectRoot), resolved.skillName);
+            await copySkillTree(resolved.sourceRoot, destRoot);
+            const doctorScript = path.join(destRoot, "bin", `${resolved.skillName}.mjs`);
+            if (await pathExists(doctorScript)) {
+                const doctorCode = io.runDoctor(doctorScript, input.projectRoot);
+                if (doctorCode !== 0) {
+                    io.error("skill doctor failed");
+                    return { ok: false, error: "skill doctor failed", doctorFailed: true };
+                }
+            }
+            const message = `Installed skill ${resolved.skillName} to ${destRoot}`;
+            io.log(message);
+            return {
+                ok: true,
+                skillName: resolved.skillName,
+                destPath: destRoot,
+                message,
+            };
+        }
+        finally {
+            if (resolved.cleanup) {
+                await resolved.cleanup();
+            }
         }
-        io.log(`Installed skill ${resolved.skillName} to ${destRoot}`);
-        return 0;
     }
-    finally {
-        if (resolved.cleanup) {
-            await resolved.cleanup();
-        }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        io.error(error);
+        return { ok: false, error };
     }
 }
 export async function runSkillsCommand(args, options = {}) {
@@ -402,7 +437,15 @@ export async function runSkillsCommand(args, options = {}) {
             await listSkills(projectRoot, io);
             return 0;
         }
-        return await installSkill(projectRoot, parsed, io);
+        const result = await installProjectSkill({
+            projectRoot,
+            fromPath: parsed.fromPath,
+            fromZip: parsed.fromZip,
+            skillName: parsed.skillName,
+            checksum: parsed.checksum,
+            io,
+        });
+        return result.ok ? 0 : 1;
     }
     catch (err) {
         io.error(err instanceof Error ? err.message : String(err));

package/dist/cli/validateCommand.d.ts

@@ -1,5 +1,5 @@
 import { validateCatalog as defaultValidateCatalog, type ValidationResult } from "../config/validateCatalog.js";
-export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]\n\n  With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).\n  --pipeline validates one pipeline file (includes uses:/include: transitively).\n  --task validates one task file.\n  --trigger validates one trigger file, including its pipeline/task refs.";
+export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--project-root <id-or-path>] [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]\n\n  With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).\n  --pipeline validates one pipeline file (includes uses:/include: transitively).\n  --task validates one task file.\n  --trigger validates one trigger file, including its pipeline/task refs.";
 export type ValidateCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/validateCommand.js

@@ -1,7 +1,8 @@
 import { validateCatalog as defaultValidateCatalog, } from "../config/validateCatalog.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
+import { resolveCliProjectRootLocal } from "./resolveCliProjectRoot.js";
 export const VALIDATE_USAGE = `Usage:
-  sf validate [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]
+  sf validate [--project-root <id-or-path>] [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]
 
   With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).
   --pipeline validates one pipeline file (includes uses:/include: transitively).
@@ -18,6 +19,7 @@ function parseValidateArgs(args) {
     if (args[0] === "--help" || args[0] === "-h") {
         return { help: true, strict: false, json: false };
     }
+    let projectRoot;
     let pipeline;
     let task;
     let trigger;
@@ -29,6 +31,13 @@ function parseValidateArgs(args) {
         if (arg === "--help" || arg === "-h") {
             help = true;
         }
+        else if (arg === "--project-root") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --project-root");
+            }
+            projectRoot = value;
+        }
         else if (arg === "--pipeline") {
             const value = args[++i];
             if (value === undefined || value.length === 0) {
@@ -67,11 +76,10 @@ function parseValidateArgs(args) {
     if (scopedFlagCount > 1) {
         throw new Error("Use at most one of --pipeline, --task, or --trigger");
     }
-    return { help, pipeline, task, trigger, strict, json };
+    return { help, projectRoot, pipeline, task, trigger, strict, json };
 }
 export async function runValidateCommand(args, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
+    const shellCwd = options.cwd ?? process.cwd();
     const out = { ...defaultIo, ...options.io };
     const validateCatalogFn = options.validateCatalog ?? defaultValidateCatalog;
     try {
@@ -80,6 +88,16 @@ export async function runValidateCommand(args, options = {}) {
             out.error(VALIDATE_USAGE);
             return 0;
         }
+        let cwd = shellCwd;
+        let projectRoot = options.projectRoot ?? shellCwd;
+        if (parsed.projectRoot !== undefined) {
+            const resolved = resolveCliProjectRootLocal(parsed.projectRoot);
+            if (!resolved) {
+                throw new Error(`Unknown project_root: ${parsed.projectRoot.trim()}`);
+            }
+            cwd = resolved.rootPath;
+            projectRoot = resolved.rootPath;
+        }
         const scope = parsed.pipeline
             ? "pipeline"
             : parsed.task

package/dist/cli.js

@@ -4,7 +4,7 @@ import { A2A_USAGE, runA2aCommand } from "./cli/a2aCommand.js";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { globalAgentBackendFromManifest, resolveAgentPort } from "./agent/resolveAgentPort.js";
+import { globalStageBackendFromManifest, resolveStagePort } from "./agent/resolveStagePort.js";
 import { BROWSER_USAGE, runBrowserCommand } from "./cli/browserCommand.js";
 import { ARTIFACT_USAGE, runArtifactCommand } from "./cli/artifactCommand.js";
 import { ENVELOPE_USAGE, runEnvelopeCommand, } from "./cli/envelopeCommand.js";
@@ -503,7 +503,7 @@ async function main(argv) {
         if (parsed.command === "browser") {
             return runBrowserCommand(argv.slice(3));
         }
-        const globalAgent = globalAgentBackendFromManifest(ctx.manifest);
+        const globalAgent = globalStageBackendFromManifest(ctx.manifest);
         if (parsed.command === "ui") {
             const listenHost = resolveListenHost({ flag: parsed.host });
             const tokens = loadControlTokens();
@@ -512,7 +512,7 @@ async function main(argv) {
                 mcpStateless: parsed.mcpStateless,
             });
             const host = await startUiServer({
-                agent: resolveAgentPort({ global: globalAgent }),
+                agent: resolveStagePort({ global: globalAgent }),
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,
@@ -547,7 +547,7 @@ async function main(argv) {
                 mcpStateless: parsed.mcpStateless,
             });
             const host = await startMcpServer({
-                agent: resolveAgentPort({ global: globalAgent }),
+                agent: resolveStagePort({ global: globalAgent }),
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,

package/dist/config/browseCatalog.d.ts

@@ -13,6 +13,8 @@ export type PipelineStageListing = {
     gate_kinds?: StageGateKind[];
     uses_path?: string;
     inline?: boolean;
+    model?: string;
+    skill?: string;
 };
 export type PipelineListing = {
     path: string;

package/dist/config/browseCatalog.js

@@ -22,6 +22,12 @@ function mapStageListing(stage, source, projectRoot) {
     else if (source?.kind === "file") {
         listing.uses_path = repoRelPath(projectRoot, source.path);
     }
+    if (typeof stage.model === "string" && stage.model.trim() !== "") {
+        listing.model = stage.model;
+    }
+    if (typeof stage.skill === "string" && stage.skill.trim() !== "") {
+        listing.skill = stage.skill;
+    }
     return listing;
 }
 function bakedModels() {

package/dist/config/catalogRelativePath.d.ts

@@ -37,6 +37,10 @@ export declare function catalogPathErrorBody(err: CatalogPathError): {
  * otherwise require explicit — no invent.
  */
 export declare function selectCatalogRootForStart(roots: CatalogRoot[], projectRoot?: string): CatalogRoot;
+export declare function resolveDefaultWriteRoot(options: ResolveCatalogRootsOptions, projectRoot?: string): Promise<{
+    roots: CatalogRoot[];
+    wireRoot: CatalogRoot;
+}>;
 /**
  * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
  * All network-surface start-input call sites use this to avoid the hand-copy sequence.