stageflow 0.25.0 → 0.30.0

package/dist/cli.js

@@ -5,37 +5,54 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { globalAgentBackendFromManifest, resolveAgentPort } from "./agent/resolveAgentPort.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";
 import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.js";
+import { DEBUG_RUN_USAGE, runDebugRunCommand, } from "./cli/debugRunCommand.js";
+import { BACKUP_USAGE, runBackupCommand, } from "./cli/backupCommand.js";
+import { RESTORE_USAGE, runRestoreCommand, } from "./cli/restoreCommand.js";
+import { EXPORT_ALL_USAGE, runExportAllCommand, } from "./cli/exportAllCommand.js";
 import { INIT_USAGE, runInitCommand } from "./cli/initCommand.js";
 import { PROVIDERS_USAGE, runProvidersCommand } from "./cli/providersCommand.js";
 import { RUN_USAGE, runRunCommand } from "./cli/runCommand.js";
 import { RUN_STAGE_USAGE, runRunStageCommand } from "./cli/runStageCommand.js";
 import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
+import { TRIGGER_USAGE, runTriggerCommand } from "./cli/triggerCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
 import { GRAPH_USAGE, runGraphCommand } from "./cli/graphCommand.js";
 import { MIGRATE_YAML_USAGE, runMigrateYamlCommand } from "./cli/migrateYamlCommand.js";
-import { createRunStore } from "./runstore/createStore.js";
+import { DOCTOR_USAGE, runDoctorCommand } from "./cli/doctorCommand.js";
 import { resolveStageflowContext } from "./project/resolveStageflowContext.js";
 import { exitForOutcome, runStageWorker } from "./runtime/stageWorker.js";
+import { scheduleExitWithDrain } from "./runtime/stageWorkerProtocol.js";
 import { SF_STAGE_WORKER } from "./runtime/stageWorkerProtocol.js";
 import { DEFAULT_PORT, startUiServer } from "./server/http.js";
 import { startMcpServer } from "./server/mcpHost.js";
+import { resolveListenHost } from "./server/listenHost.js";
+import { assertBindAllowed, BindRefusedError, loadControlTokens, } from "./server/controlToken.js";
 import { resolveMcpStateless } from "./mcp/server.js";
-import { PACKAGE_VERSION } from "./package-meta.js";
+import { PACKAGE_VERSION, BUILD_SHA } from "./package-meta.js";
+import { installProxyDispatcher } from "./net/proxy.js";
+import { warnMissingCaPaths } from "./preflight/tls.js";
+import { logger as cliLogger } from "./logging/logger.js";
 const USAGE = `Usage:
   sf init
-  sf run --task <path> --pipeline <path> [--checkout <path>] [--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> [--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-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]
   sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
+  sf doctor [--json] [--pipeline <path>] [--strict]
   sf graph --pipeline <path> [--json]
   sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]
   sf artifact read --run <runId> --path <relPath> [--out <file>]
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]
   sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]
+  sf debug-run <runId> [--out <file>]
+  sf backup [--out <file>] [--db-only] [--no-credentials] [--include-a2a-artifacts] [--json]
+  sf restore <file> [--force] [--json]
+  sf export --all [--status <status>] [--since <iso>] [--pipeline <id-or-path>] [--out <file>]
   sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
   sf runs show --run <runId> [--from <sf-run.json>] [--json]
   sf runs verify --run <runId> --stage <stageId> [--json]
@@ -46,9 +63,9 @@ const USAGE = `Usage:
   sf runs retry --run <runId> --stage <stageId> [--json]
   sf runs resume --run <runId> --stage <stageId> [--json]
   sf runs abandon --run <runId> --stage <stageId> [--json]
-  sf runs rerun --run <runId> [--json]
-  sf ui [--port ${DEFAULT_PORT}] [--mcp-stateless]
-  sf mcp [--port ${DEFAULT_PORT}] [--mcp-stateless]
+  sf runs rerun --run <runId> [--pinned] [--json]
+  sf ui [--host <addr>] [--port ${DEFAULT_PORT}] [--no-open] [--mcp-stateless]
+  sf mcp [--host <addr>] [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf providers list
   sf providers status [--provider <id>]
   sf providers detect
@@ -58,6 +75,11 @@ const USAGE = `Usage:
   sf skills list
   sf skills install --from-path <dir> [--skill-name <name>]
   sf skills install --from-zip <url-or-path> [--skill-name <name>] [--checksum sha256:<hex>]
+  sf browser profiles [--json]
+  sf browser status <name> [--json]
+  sf browser check <name> --url <url> --logged-in <glob> [--logged-out <glob>]... [--headless] [--json]
+  sf browser login <name> --url <login-url> --logged-in <glob> [--timeout-sec <n>]
+  sf browser clear <name> [--yes]
   sf --version
   sf -V
   sf --help
@@ -76,6 +98,8 @@ ${RUN_STAGE_USAGE}
 
 ${VALIDATE_USAGE}
 
+${DOCTOR_USAGE}
+
 ${GRAPH_USAGE}
 
 ${A2A_USAGE}
@@ -88,11 +112,23 @@ ${ENVELOPE_USAGE}
 
 ${EXPORT_RUN_USAGE}
 
+${DEBUG_RUN_USAGE}
+
+${BACKUP_USAGE}
+
+${RESTORE_USAGE}
+
+${EXPORT_ALL_USAGE}
+
 ${RUNS_USAGE}
 
+${TRIGGER_USAGE}
+
 ${PROVIDERS_USAGE}
 
-${SKILLS_USAGE}`;
+${SKILLS_USAGE}
+
+${BROWSER_USAGE}`;
 function parseArgs(argv) {
     const args = argv.slice(2);
     if (args.length === 0) {
@@ -103,14 +139,17 @@ function parseArgs(argv) {
         return { help: true };
     }
     if (args[0] === "--version" || args[0] === "-V") {
-        if (args.length > 1) {
-            throw new Error(`Unexpected argument: ${args[1]}`);
+        const versionJson = args.includes("--json");
+        const rest = args.slice(1).filter((a) => a !== "--json");
+        if (rest.length > 0) {
+            throw new Error(`Unexpected argument: ${rest[0]}`);
         }
-        return { help: false, version: true };
+        return { help: false, version: true, versionJson };
     }
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
+        command === "doctor" ||
         command === "graph" ||
         command === "a2a" ||
         command === "migrate-yaml" ||
@@ -120,8 +159,14 @@ function parseArgs(argv) {
         command === "artifact" ||
         command === "envelope" ||
         command === "export-run" ||
+        command === "debug-run" ||
+        command === "backup" ||
+        command === "restore" ||
+        command === "export" ||
         command === "runs" ||
-        command === "skills") {
+        command === "trigger" ||
+        command === "skills" ||
+        command === "browser") {
         return { help: false, command };
     }
     if (args.includes("--help") || args.includes("-h")) {
@@ -130,7 +175,11 @@ function parseArgs(argv) {
     let task;
     let pipeline;
     let port;
+    let host;
+    let noOpen = false;
     let checkout;
+    let repository;
+    let ref;
     let mcpStateless = false;
     for (let i = 1; i < args.length; i++) {
         if (args[i] === "--task") {
@@ -146,6 +195,20 @@ function parseArgs(argv) {
             }
             checkout = raw;
         }
+        else if (args[i] === "--repository") {
+            const raw = args[++i];
+            if (raw === undefined || raw.length === 0) {
+                throw new Error("Missing value for --repository");
+            }
+            repository = raw;
+        }
+        else if (args[i] === "--ref") {
+            const raw = args[++i];
+            if (raw === undefined || raw.length === 0) {
+                throw new Error("Missing value for --ref");
+            }
+            ref = raw;
+        }
         else if (args[i] === "--port") {
             const raw = args[++i];
             port = Number(raw);
@@ -153,11 +216,33 @@ function parseArgs(argv) {
                 throw new Error(`Invalid --port: ${raw}`);
             }
         }
+        else if (args[i] === "--host") {
+            const raw = args[++i];
+            if (raw === undefined || raw.length === 0) {
+                throw new Error("Missing value for --host");
+            }
+            host = raw;
+        }
+        else if (args[i] === "--no-open") {
+            noOpen = true;
+        }
         else if (args[i] === "--mcp-stateless") {
             mcpStateless = true;
         }
     }
-    return { help: false, command, task, pipeline, port, checkout, mcpStateless };
+    return {
+        help: false,
+        command,
+        task,
+        pipeline,
+        port,
+        host,
+        noOpen,
+        checkout,
+        repository,
+        ref,
+        mcpStateless,
+    };
 }
 export function parseRunStageArgs(argv) {
     let runId;
@@ -254,6 +339,9 @@ async function handleInternalRunStage(argv) {
     if (process.env[SF_STAGE_WORKER] !== "1") {
         process.env[SF_STAGE_WORKER] = "1";
     }
+    installProxyDispatcher(process.env, {
+        log: (msg) => cliLogger.info("proxy.dispatcher", msg),
+    });
     const parsed = parseRunStageArgs(argv);
     const outcome = await runStageWorker({
         runId: parsed.runId,
@@ -267,29 +355,55 @@ async function handleInternalRunStage(argv) {
         operatorCatalog: parsed.operatorCatalog,
         skipGates: parsed.skipGates,
     });
-    exitForOutcome(outcome);
+    return exitForOutcome(outcome);
 }
 function openBrowser(url) {
     const platform = process.platform;
+    let child;
     if (platform === "darwin") {
-        spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+        child = spawn("open", [url], { detached: true, stdio: "ignore" });
     }
     else if (platform === "win32") {
-        spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+        child = spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" });
     }
     else {
-        spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+        child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
     }
+    child.on("error", () => { });
+    child.unref();
+}
+function isNoOpenEnabled(flag, env = process.env) {
+    if (flag)
+        return true;
+    const raw = env.STAGEFLOW_NO_OPEN;
+    if (raw === undefined || raw.trim() === "")
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized !== "0" && normalized !== "false";
 }
 async function main(argv) {
     try {
+        installProxyDispatcher(process.env, {
+            log: (msg) => cliLogger.info("proxy.dispatcher", msg),
+        });
+        for (const warning of warnMissingCaPaths(process.env)) {
+            cliLogger.warn("tls.ca_missing", `${warning.name} points to missing path: ${warning.path}`);
+        }
         const parsed = parseArgs(argv);
         if (parsed.help) {
             console.log(USAGE);
             return argv.slice(2).length === 0 ? 1 : 0;
         }
         if (parsed.version) {
-            console.log(PACKAGE_VERSION);
+            if (parsed.versionJson) {
+                console.log(JSON.stringify({
+                    version: PACKAGE_VERSION,
+                    build_sha: BUILD_SHA,
+                }));
+            }
+            else {
+                console.log(PACKAGE_VERSION);
+            }
             return 0;
         }
         const ctx = await resolveStageflowContext(process.cwd());
@@ -305,6 +419,9 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
+        if (parsed.command === "doctor") {
+            return runDoctorCommand(argv.slice(3), { cwd: ctx.invocationCwd });
+        }
         if (parsed.command === "graph") {
             return runGraphCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,
@@ -345,11 +462,35 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
+        if (parsed.command === "debug-run") {
+            return runDebugRunCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
+        if (parsed.command === "backup") {
+            return runBackupCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+            });
+        }
+        if (parsed.command === "restore") {
+            return runRestoreCommand(argv.slice(3));
+        }
+        if (parsed.command === "export") {
+            return runExportAllCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+            });
+        }
         if (parsed.command === "runs") {
             return runRunsCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,
             });
         }
+        if (parsed.command === "trigger") {
+            return runTriggerCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+            });
+        }
         if (parsed.command === "providers") {
             return runProvidersCommand(argv.slice(3), ctx.invocationCwd);
         }
@@ -359,41 +500,64 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
-        const store = createRunStore({ rootDir: ctx.globalHome });
+        if (parsed.command === "browser") {
+            return runBrowserCommand(argv.slice(3));
+        }
         const globalAgent = globalAgentBackendFromManifest(ctx.manifest);
         if (parsed.command === "ui") {
+            const listenHost = resolveListenHost({ flag: parsed.host });
+            const tokens = loadControlTokens();
+            assertBindAllowed(listenHost, tokens);
             const mcpStateless = resolveMcpStateless({
                 mcpStateless: parsed.mcpStateless,
             });
-            const { url, mcpUrl } = await startUiServer({
+            const host = await startUiServer({
                 agent: resolveAgentPort({ global: globalAgent }),
-                store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,
+                host: listenHost,
                 mcpStateless,
+                controlTokens: tokens,
             });
-            console.log(`Operator console: ${url}`);
-            console.log(`MCP endpoint: ${mcpUrl}`);
-            openBrowser(url);
-            await new Promise(() => undefined);
-            return 0;
+            if (host.store) {
+                try {
+                    await host.store.ensureProject(ctx.projectRoot);
+                }
+                catch {
+                    // The console still serves seeded catalogs when this project cannot be registered.
+                }
+            }
+            console.log(`Operator console: ${host.url}`);
+            console.log(`MCP endpoint: ${host.mcpUrl}`);
+            if (!isNoOpenEnabled(parsed.noOpen)) {
+                openBrowser(host.url);
+            }
+            const outcome = await host.shutdown.whenDrained();
+            return outcome.exitCode;
         }
         if (parsed.command === "mcp") {
+            if (parsed.noOpen) {
+                throw new Error("--no-open is only valid with sf ui");
+            }
+            const listenHost = resolveListenHost({ flag: parsed.host });
+            const tokens = loadControlTokens();
+            assertBindAllowed(listenHost, tokens);
             const mcpStateless = resolveMcpStateless({
                 mcpStateless: parsed.mcpStateless,
             });
-            const { mcpUrl } = await startMcpServer({
+            const host = await startMcpServer({
                 agent: resolveAgentPort({ global: globalAgent }),
-                store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,
+                host: listenHost,
                 mcpStateless,
+                controlTokens: tokens,
             });
-            console.log(`MCP endpoint: ${mcpUrl}`);
-            await new Promise(() => undefined);
-            return 0;
+            console.log(`MCP endpoint: ${host.mcpUrl}`);
+            const outcome = await host.shutdown.whenDrained();
+            return outcome.exitCode;
         }
         if (parsed.command === "internal") {
             const subArgs = argv.slice(3);
@@ -409,6 +573,10 @@ async function main(argv) {
         return 1;
     }
     catch (err) {
+        if (err instanceof BindRefusedError) {
+            console.error(err.message);
+            return err.exitCode;
+        }
         console.error(err instanceof Error ? err.message : String(err));
         return 1;
     }
@@ -433,9 +601,11 @@ function isDirectCliInvocation() {
 }
 if (isDirectCliInvocation()) {
     main(process.argv)
-        .then((code) => process.exit(code))
+        .then((code) => {
+        scheduleExitWithDrain(code);
+    })
         .catch((err) => {
         console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        scheduleExitWithDrain(1);
     });
 }

package/dist/config/browseCatalog.d.ts

@@ -37,6 +37,7 @@ export type CatalogBrowseResult = {
 export type CatalogScanPaths = {
     pipelinePaths: string[];
     taskPaths: string[];
+    triggerPaths: string[];
 };
 export declare function getCatalogScanPaths(ctx: CatalogContext): Promise<CatalogScanPaths | null>;
 export declare function browseCatalog(invocationCwd: string | StageflowContext): Promise<CatalogBrowseResult>;

package/dist/config/browseCatalog.js

@@ -28,7 +28,7 @@ function bakedModels() {
     return [...BAKED_MODEL_IDS].sort((a, b) => a.localeCompare(b));
 }
 function catalogReadyFromStageflow(ctx) {
-    return ctx.isGitProject && ctx.manifestStatus === "ok" && ctx.manifest !== null;
+    return ctx.manifestStatus === "ok" && ctx.manifest !== null;
 }
 function catalogReady(ctx) {
     return ctx.manifestStatus === "ok" && ctx.projectRoot !== null && ctx.manifest !== null;
@@ -37,11 +37,12 @@ export async function getCatalogScanPaths(ctx) {
     if (!catalogReady(ctx)) {
         return null;
     }
-    const [pipelinePaths, taskPaths] = await Promise.all([
+    const [pipelinePaths, taskPaths, triggerPaths] = await Promise.all([
         scanCatalogPaths(ctx.manifest, "pipeline"),
         scanCatalogPaths(ctx.manifest, "task"),
+        scanCatalogPaths(ctx.manifest, "trigger"),
     ]);
-    return { pipelinePaths, taskPaths };
+    return { pipelinePaths, taskPaths, triggerPaths };
 }
 async function listTasksFromManifest(projectRoot, manifest, warnings) {
     const filePaths = await scanCatalogPaths(manifest, "task");
@@ -122,7 +123,7 @@ export async function browseCatalog(invocationCwd) {
         ? await resolveStageflowContext(invocationCwd)
         : invocationCwd;
     const base = {
-        projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
+        projectRoot: ctx.manifestStatus === "not_git" ? null : ctx.projectRoot,
         manifest: ctx.manifest,
         manifestStatus: ctx.manifestStatus,
         issues: ctx.manifestIssues,

package/dist/config/builtinSkills.d.ts

@@ -0,0 +1,4 @@
+export declare const BROWSER_SKILL_NAME = "browser";
+export declare function isBuiltinSkillName(name: string): boolean;
+/** Absolute SKILL.md of a skill shipped inside the package, if present on disk. */
+export declare function resolveBuiltinSkillFile(name: string, fromUrl?: string): string | undefined;

package/dist/config/builtinSkills.js

@@ -0,0 +1,23 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const BROWSER_SKILL_NAME = "browser";
+const BUILTIN_SKILL_NAMES = new Set([BROWSER_SKILL_NAME]);
+export function isBuiltinSkillName(name) {
+    return BUILTIN_SKILL_NAMES.has(name);
+}
+/** Absolute SKILL.md of a skill shipped inside the package, if present on disk. */
+export function resolveBuiltinSkillFile(name, fromUrl = import.meta.url) {
+    if (!isBuiltinSkillName(name))
+        return undefined;
+    const here = path.dirname(fileURLToPath(fromUrl));
+    for (const root of [
+        path.resolve(here, "../../builtin-skills"),
+        path.resolve(here, "../../../builtin-skills"),
+    ]) {
+        const file = path.join(root, name, "SKILL.md");
+        if (existsSync(file))
+            return file;
+    }
+    return undefined;
+}

package/dist/config/catalogRelativePath.d.ts

@@ -0,0 +1,63 @@
+import type { CatalogRoot, ResolveCatalogRootsOptions } from "./resolveCatalogRoots.js";
+export type CatalogPathErrorCode = "absolute_path_not_allowed" | "path_outside_project_root" | "unknown_project_root" | "catalog_root_read_only";
+export declare class CatalogPathError extends Error {
+    readonly code: CatalogPathErrorCode;
+    readonly registered_roots: string[];
+    constructor(message: string, code: CatalogPathErrorCode, registered_roots: string[]);
+}
+export declare function isInsideProjectRoot(projectRoot: string, candidate: string): boolean;
+export type ResolveCatalogRelativePathInput = {
+    /** Caller-supplied path (pipeline, task, etc.). */
+    inputPath: string;
+    /** Optional wire project_root (symbolic seeded id or absolute). */
+    projectRoot?: string;
+    roots: CatalogRoot[];
+    fieldName?: string;
+};
+export type ResolvedCatalogPath = {
+    absolutePath: string;
+    root: CatalogRoot;
+    relativePath: string;
+};
+/**
+ * Network-surface path contract: refuse absolute paths; resolve relative under
+ * a selected catalog root; refuse `..` escape via realpath containment.
+ */
+export declare function resolveCatalogRelativePath(input: ResolveCatalogRelativePathInput): ResolvedCatalogPath;
+export declare function catalogPathErrorBody(err: CatalogPathError): {
+    error: string;
+    code: CatalogPathErrorCode;
+    registered_roots: string[];
+    hint?: string;
+};
+/**
+ * Pick the catalog root for start_run / POST /api/runs.
+ * Wire project_root (symbolic seeded id or absolute) maps to CatalogRoot.path
+ * (absolute store key). When omitted: sole root, or sole non-seeded root;
+ * otherwise require explicit — no invent.
+ */
+export declare function selectCatalogRootForStart(roots: CatalogRoot[], projectRoot?: string): CatalogRoot;
+/**
+ * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
+ * All network-surface start-input call sites use this to avoid the hand-copy sequence.
+ */
+export declare function resolveCatalogStartInput(options: ResolveCatalogRootsOptions, projectRoot?: string): Promise<{
+    roots: CatalogRoot[];
+    wireRoot: CatalogRoot;
+}>;
+/**
+ * Like resolveCatalogStartInput but additionally refuses read-only roots.
+ * Used by write surfaces (POST /api/stages, POST /api/pipelines).
+ */
+export declare function resolveWritableCatalogRoot(options: ResolveCatalogRootsOptions, projectRoot?: string): Promise<{
+    roots: CatalogRoot[];
+    wireRoot: CatalogRoot;
+}>;
+/**
+ * Local CLI control: turn a cwd-resolved filesystem path into a catalog-relative
+ * wire path + project_root so the network surface does not see an absolute path.
+ */
+export declare function relativizeLocalPathForNetwork(cwd: string, inputPath: string): {
+    path: string;
+    project_root: string;
+};