stageflow 0.23.0 → 0.27.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { A2A_USAGE, runA2aCommand } from "./cli/a2aCommand.js";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,32 +8,49 @@ import { globalAgentBackendFromManifest, resolveAgentPort } from "./agent/resolv
 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 { 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]
@@ -43,9 +61,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 +76,8 @@ const USAGE = `Usage:
   sf --version
   sf -V
   sf --help
+  sf a2a validate|list [--config <path>]
+  sf a2a add-caller <id> [--config <path>] [--token-env <NAME>]
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
 
@@ -67,10 +87,16 @@ ${INIT_USAGE}
 
 ${RUN_USAGE}
 
+${RUN_STAGE_USAGE}
+
 ${VALIDATE_USAGE}
 
+${DOCTOR_USAGE}
+
 ${GRAPH_USAGE}
 
+${A2A_USAGE}
+
 ${MIGRATE_YAML_USAGE}
 
 ${ARTIFACT_USAGE}
@@ -79,6 +105,14 @@ ${ENVELOPE_USAGE}
 
 ${EXPORT_RUN_USAGE}
 
+${DEBUG_RUN_USAGE}
+
+${BACKUP_USAGE}
+
+${RESTORE_USAGE}
+
+${EXPORT_ALL_USAGE}
+
 ${RUNS_USAGE}
 
 ${PROVIDERS_USAGE}
@@ -94,21 +128,30 @@ 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" ||
         command === "run" ||
+        command === "run-stage" ||
         command === "init" ||
         command === "artifact" ||
         command === "envelope" ||
         command === "export-run" ||
+        command === "debug-run" ||
+        command === "backup" ||
+        command === "restore" ||
+        command === "export" ||
         command === "runs" ||
         command === "skills") {
         return { help: false, command };
@@ -119,7 +162,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") {
@@ -135,6 +182,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);
@@ -142,11 +203,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;
@@ -243,6 +326,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,
@@ -256,32 +342,61 @@ 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());
+        if (parsed.command === "a2a") {
+            return runA2aCommand(argv.slice(3), { cwd: ctx.invocationCwd, projectRoot: ctx.projectRoot });
+        }
         if (parsed.command === "init") {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
         }
@@ -291,6 +406,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,
@@ -308,6 +426,11 @@ async function main(argv) {
                 cwd: ctx.invocationCwd,
             });
         }
+        if (parsed.command === "run-stage") {
+            return runRunStageCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+            });
+        }
         if (parsed.command === "artifact") {
             return runArtifactCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,
@@ -326,6 +449,25 @@ 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,
@@ -340,41 +482,53 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
-        const store = createRunStore({ rootDir: ctx.globalHome });
         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;
+            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);
@@ -390,6 +544,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;
     }
@@ -414,9 +572,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/catalogRelativePath.d.ts

@@ -0,0 +1,62 @@
+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[];
+};
+/**
+ * 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;
+};

package/dist/config/catalogRelativePath.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { findCatalogRoot, resolveCatalogRoots } from "./resolveCatalogRoots.js";
+export class CatalogPathError extends Error {
+    code;
+    registered_roots;
+    constructor(message, code, registered_roots) {
+        super(message);
+        this.name = "CatalogPathError";
+        this.code = code;
+        this.registered_roots = registered_roots;
+    }
+}
+function realOrResolve(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+export function isInsideProjectRoot(projectRoot, candidate) {
+    const rootReal = realOrResolve(projectRoot);
+    const candidateReal = realOrResolve(candidate);
+    const rel = path.relative(rootReal, candidateReal);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Network-surface path contract: refuse absolute paths; resolve relative under
+ * a selected catalog root; refuse `..` escape via realpath containment.
+ */
+export function resolveCatalogRelativePath(input) {
+    const field = input.fieldName ?? "path";
+    const registered = input.roots.map((r) => r.project_root);
+    if (path.isAbsolute(input.inputPath)) {
+        throw new CatalogPathError(`Absolute ${field} is not allowed on network surfaces; use a catalog-relative path under a registered project_root, or an inline definition.`, "absolute_path_not_allowed", registered);
+    }
+    const root = selectCatalogRootForStart(input.roots, input.projectRoot);
+    const absolutePath = path.resolve(root.path, input.inputPath);
+    if (!isInsideProjectRoot(root.path, absolutePath)) {
+        throw new CatalogPathError(`${field} escapes project_root ${root.project_root}`, "path_outside_project_root", registered);
+    }
+    return {
+        absolutePath,
+        root,
+        relativePath: path.relative(root.path, absolutePath).replace(/\\/g, "/"),
+    };
+}
+export function catalogPathErrorBody(err) {
+    return {
+        error: err.message,
+        code: err.code,
+        registered_roots: err.registered_roots,
+    };
+}
+/**
+ * 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 function selectCatalogRootForStart(roots, projectRoot) {
+    const registered = roots.map((r) => r.project_root);
+    if (projectRoot !== undefined) {
+        const found = findCatalogRoot(roots, projectRoot);
+        if (found === undefined) {
+            throw new CatalogPathError(`Unknown project_root: ${projectRoot}`, "unknown_project_root", registered);
+        }
+        return found;
+    }
+    if (roots.length === 0) {
+        throw new CatalogPathError("No catalog roots configured; ensure a project_root first", "unknown_project_root", registered);
+    }
+    if (roots.length === 1) {
+        return roots[0];
+    }
+    const writable = roots.filter((r) => r.kind !== "seeded");
+    if (writable.length === 1) {
+        return writable[0];
+    }
+    throw new CatalogPathError("project_root is required when multiple catalog roots are configured", "unknown_project_root", registered);
+}
+/**
+ * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
+ * All network-surface start-input call sites use this to avoid the hand-copy sequence.
+ */
+export async function resolveCatalogStartInput(options, projectRoot) {
+    const roots = await resolveCatalogRoots(options);
+    const wireRoot = selectCatalogRootForStart(roots, projectRoot);
+    return { roots, wireRoot };
+}
+/**
+ * Like resolveCatalogStartInput but additionally refuses read-only roots.
+ * Used by write surfaces (POST /api/stages, POST /api/pipelines).
+ */
+export async function resolveWritableCatalogRoot(options, projectRoot) {
+    const { roots, wireRoot } = await resolveCatalogStartInput(options, projectRoot);
+    if (wireRoot.read_only) {
+        throw new CatalogPathError(`Catalog root ${wireRoot.project_root} is read-only`, "catalog_root_read_only", roots.map((r) => r.project_root));
+    }
+    return { roots, wireRoot };
+}
+/**
+ * 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 function relativizeLocalPathForNetwork(cwd, inputPath) {
+    const abs = realOrResolve(path.resolve(cwd, inputPath));
+    const cwdAbs = realOrResolve(cwd);
+    const rel = path.relative(cwdAbs, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`Path ${abs} is outside CLI cwd ${cwdAbs}; run from the project root, pass a path under cwd, or use an inline definition on the Host API`);
+    }
+    return {
+        path: rel === "" ? "." : rel.replace(/\\/g, "/"),
+        project_root: cwdAbs,
+    };
+}

package/dist/config/configOrigin.d.ts

@@ -0,0 +1,27 @@
+export type ConfigOriginKind = "catalog" | "inline" | "workspace" | "seeded";
+export type ConfigOriginRecord = {
+    name: string;
+    origin: ConfigOriginKind;
+    path?: string;
+};
+export type BindingKindForOrigin = "repository" | "checkout" | "none";
+export type TrustWorkspaceDecision = {
+    allow: boolean;
+    origin: ConfigOriginKind;
+    code?: "untrusted_config_origin";
+    message?: string;
+};
+export declare function bindingKindForOrigin(kind: "repository" | "checkout" | "unbound" | "none" | undefined): BindingKindForOrigin;
+/**
+ * Decide whether workspace-sourced config (.mcp.json / skills under checkout)
+ * is permitted. Default: refuse for repository bindings; allow for checkout;
+ * host trust_workspace_config can allowlisted roots.
+ */
+export declare function decideWorkspaceConfigTrust(options: {
+    bindingKind: BindingKindForOrigin;
+    projectRoot: string;
+    trustWorkspaceConfig?: string[];
+    source: "workspace" | "catalog" | "inline" | "seeded";
+}): TrustWorkspaceDecision;
+export declare function skillOriginKind(scope: "user" | "project" | "temporary", filePath: string, checkoutRoot: string | undefined): ConfigOriginKind;
+export declare function catalogOrSeededOrigin(projectRoot: string | undefined, seededRoots: readonly string[]): ConfigOriginKind;