stageflow 0.25.0 → 0.30.0

package/dist/config/hostConfig.js

@@ -0,0 +1,360 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { readSecretFromEnvOrFile } from "./secretFromEnvOrFile.js";
+export class HostConfigError extends Error {
+    code;
+    key;
+    constructor(message, code, key) {
+        super(message);
+        this.name = "HostConfigError";
+        this.code = code;
+        this.key = key;
+    }
+}
+/** Env keys that are known STAGEFLOW_* (or dynamic families) so unknown-key check accepts them. */
+export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
+    "STAGEFLOW_HOME",
+    "STAGEFLOW_BIND",
+    "STAGEFLOW_ALLOWED_HOSTS",
+    "STAGEFLOW_CONTROL_TOKEN",
+    "STAGEFLOW_CONTROL_TOKEN_FILE",
+    "STAGEFLOW_READ_TOKEN",
+    "STAGEFLOW_READ_TOKEN_FILE",
+    "STAGEFLOW_ALLOW_UNKNOWN_CONFIG",
+    "STAGEFLOW_MAX_CONCURRENT_RUNS",
+    "STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT",
+    "STAGEFLOW_MAX_QUEUED",
+    "STAGEFLOW_REQUIRE_PROVIDERS",
+    "STAGEFLOW_A2A_CONFIG",
+    "STAGEFLOW_ACTIVITY_TEXT_LIMIT",
+    "STAGEFLOW_ACTIVITY_VERBOSE",
+    "STAGEFLOW_CURSOR_EXTENSION",
+    "STAGEFLOW_NO_OPEN",
+    "STAGEFLOW_OPERATOR_CWD",
+    "STAGEFLOW_OPERATOR_AGENT_DIR",
+    "STAGEFLOW_LEGACY_YAML",
+    "STAGEFLOW_LOG_FORMAT",
+    "STAGEFLOW_LOG_LEVEL",
+    "STAGEFLOW_LOG_MAX_LINE_BYTES",
+    "STAGEFLOW_MCP_STATELESS",
+    "STAGEFLOW_DISK_WARN_BYTES",
+    "STAGEFLOW_MIN_FREE_DISK_BYTES",
+    "STAGEFLOW_BARE_CACHE_TTL_MS",
+    "STAGEFLOW_SLIM_ARTIFACT_MAX_BYTES",
+    "STAGEFLOW_SQLITE_BUSY_TIMEOUT_MS",
+    "STAGEFLOW_RUN_BRANCH_TEMPLATE",
+    "STAGEFLOW_AUTO_RESUME_INTERRUPTED",
+    "STAGEFLOW_MAX_AUTO_RESUMES",
+    "STAGEFLOW_RETRY_ROOT_WAIT_TIMEOUT_MS",
+    "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN",
+    "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES",
+    "STAGEFLOW_STAGE_EXECUTION",
+    "STAGEFLOW_STAGE_ENV_ALLOW",
+    "STAGEFLOW_STAGE_ENV_PASSTHROUGH",
+    "STAGEFLOW_GC_INTERVAL_MS",
+    "STAGEFLOW_MAX_CONNECTIONS",
+    "STAGEFLOW_REQUEST_TIMEOUT_MS",
+    "STAGEFLOW_AUTOSTART_TIMEOUT_MS",
+    "STAGEFLOW_NO_AUTOSTART",
+    "STAGEFLOW_SERVICE_PORT",
+    "STAGEFLOW_SHUTDOWN_GRACE_MS",
+    "STAGEFLOW_TOOLCHAIN_MANIFEST",
+    "STAGEFLOW_SECRET_REGISTRY",
+    "STAGEFLOW_BUILD_SHA",
+    "STAGEFLOW_TRIGGER_TICK_INTERVAL_MS",
+    "STAGEFLOW_GITHUB_POLL_INTERVAL_MS",
+]);
+const KNOWN_ENV_PREFIXES = [
+    "STAGEFLOW_PROVIDER_",
+    "STAGEFLOW_SLIM_",
+    "STAGEFLOW_PURGE_",
+    "STAGEFLOW_CONTROL_TOKEN_",
+];
+const FILE_KEY_TO_FIELD = {
+    max_concurrent_runs: "maxConcurrentRuns",
+    max_concurrent_runs_per_project: "maxConcurrentRunsPerProject",
+    max_queued: "maxQueued",
+    require_providers: "requireProviders",
+    trust_workspace_config: "trustWorkspaceConfig",
+    allow_unknown_config: "allowUnknownConfig",
+    callers: "callers",
+    browser: "browser",
+};
+const DEFAULT_MAX_CONCURRENT = 3;
+const DEFAULT_MAX_QUEUED = 32;
+function isKnownStageflowEnvKey(key) {
+    if (KNOWN_STAGEFLOW_ENV_KEYS.has(key))
+        return true;
+    return KNOWN_ENV_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+function parsePositiveInt(raw, key, opts) {
+    const n = Number.parseInt(raw, 10);
+    const min = opts?.allowZero ? 0 : 1;
+    if (!Number.isFinite(n) || n < min || String(n) !== raw.trim()) {
+        throw new HostConfigError(`Invalid value for ${key}: ${JSON.stringify(raw)}`, "config_invalid", key);
+    }
+    return n;
+}
+function parseStringList(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function parseBool(raw, key) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "1" || normalized === "true")
+        return true;
+    if (normalized === "0" || normalized === "false" || normalized === "") {
+        return false;
+    }
+    throw new HostConfigError(`Invalid boolean for ${key}: ${JSON.stringify(raw)}`, "config_invalid", key);
+}
+function assertUnknownEnvKeys(env, allowUnknown, warnings) {
+    for (const key of Object.keys(env)) {
+        if (!key.startsWith("STAGEFLOW_"))
+            continue;
+        if (isKnownStageflowEnvKey(key))
+            continue;
+        const message = `Unknown environment variable ${key}`;
+        if (allowUnknown) {
+            warnings.push(message);
+            continue;
+        }
+        throw new HostConfigError(message, "config_unknown_key", key);
+    }
+}
+function loadFileLayers(filePath) {
+    const warnings = [];
+    if (filePath === undefined || !existsSync(filePath)) {
+        return { values: {}, warnings };
+    }
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HostConfigError(`Invalid config file ${filePath}: ${detail}`, "config_invalid");
+    }
+    if (raw === null || raw === undefined) {
+        return { values: {}, warnings };
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new HostConfigError(`config.yaml must be a mapping`, "config_invalid");
+    }
+    const values = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const field = FILE_KEY_TO_FIELD[key];
+        if (field === undefined) {
+            throw new HostConfigError(`Unknown config key "${key}" in ${filePath}`, "config_unknown_key", key);
+        }
+        values[field] = value;
+    }
+    return { values, warnings };
+}
+function coerceFileNumber(value, key) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return parsePositiveInt(value, key, {
+            allowZero: key.includes("queued") || key.includes("per_project"),
+        });
+    }
+    throw new HostConfigError(`Invalid value for ${key}`, "config_invalid", key);
+}
+function coerceFileStringList(value, key) {
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value.map((v) => v.trim()).filter((v) => v.length > 0);
+    }
+    if (typeof value === "string")
+        return parseStringList(value);
+    throw new HostConfigError(`Invalid value for ${key}; expected string list`, "config_invalid", key);
+}
+function coerceFileBool(value, key) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return parseBool(value, key);
+    throw new HostConfigError(`Invalid boolean for ${key}`, "config_invalid", key);
+}
+function coerceCallers(value, key) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new HostConfigError(`Invalid value for ${key}; expected mapping of caller_id → { max_concurrent }`, "config_invalid", key);
+    }
+    const out = {};
+    for (const [rawId, rawEntry] of Object.entries(value)) {
+        const callerId = rawId.trim().toLowerCase();
+        if (callerId.length === 0) {
+            throw new HostConfigError(`Invalid empty caller id in ${key}`, "config_invalid", key);
+        }
+        if (rawEntry === null ||
+            typeof rawEntry !== "object" ||
+            Array.isArray(rawEntry)) {
+            throw new HostConfigError(`Invalid value for ${key}.${rawId}; expected { max_concurrent }`, "config_invalid", key);
+        }
+        const entry = rawEntry;
+        if (entry.max_concurrent === undefined) {
+            throw new HostConfigError(`Missing max_concurrent for ${key}.${rawId}`, "config_invalid", key);
+        }
+        const n = coerceFileNumber(entry.max_concurrent, `${key}.${rawId}.max_concurrent`);
+        if (!Number.isInteger(n) || n < 1) {
+            throw new HostConfigError(`Invalid max_concurrent for ${key}.${rawId}`, "config_invalid", key);
+        }
+        for (const sub of Object.keys(entry)) {
+            if (sub !== "max_concurrent") {
+                throw new HostConfigError(`Unknown key "${sub}" under ${key}.${rawId}`, "config_unknown_key", sub);
+            }
+        }
+        out[callerId] = { maxConcurrent: n };
+    }
+    return out;
+}
+/**
+ * Assemble HostConfig once at boot. Precedence: overrides (CLI flags) > env > file > default.
+ */
+export function loadHostConfig(options) {
+    const env = options?.env ?? process.env;
+    const warnings = [];
+    const homeDir = options?.homeDir ?? globalStageflowHome();
+    const configFilePath = options?.configFilePath === null
+        ? undefined
+        : (options?.configFilePath ?? path.join(homeDir, "config.yaml"));
+    const allowUnknownFromEnv = env.STAGEFLOW_ALLOW_UNKNOWN_CONFIG;
+    const allowUnknownConfig = allowUnknownFromEnv !== undefined && allowUnknownFromEnv.length > 0
+        ? parseBool(allowUnknownFromEnv, "STAGEFLOW_ALLOW_UNKNOWN_CONFIG")
+        : false;
+    if (allowUnknownConfig) {
+        warnings.push("STAGEFLOW_ALLOW_UNKNOWN_CONFIG=1: unknown STAGEFLOW_* keys will warn instead of failing boot");
+    }
+    assertUnknownEnvKeys(env, allowUnknownConfig, warnings);
+    const file = loadFileLayers(configFilePath !== undefined && existsSync(configFilePath)
+        ? configFilePath
+        : undefined);
+    warnings.push(...file.warnings);
+    let maxConcurrentRuns = DEFAULT_MAX_CONCURRENT;
+    let maxConcurrentRunsExplicit = false;
+    if (file.values.maxConcurrentRuns !== undefined) {
+        const n = coerceFileNumber(file.values.maxConcurrentRuns, "max_concurrent_runs");
+        if (!Number.isInteger(n) || n < 1) {
+            throw new HostConfigError(`Invalid value for max_concurrent_runs`, "config_invalid", "max_concurrent_runs");
+        }
+        maxConcurrentRuns = n;
+        maxConcurrentRunsExplicit = true;
+    }
+    if (env.STAGEFLOW_MAX_CONCURRENT_RUNS !== undefined) {
+        maxConcurrentRuns = parsePositiveInt(env.STAGEFLOW_MAX_CONCURRENT_RUNS, "STAGEFLOW_MAX_CONCURRENT_RUNS");
+        maxConcurrentRunsExplicit = true;
+    }
+    if (options?.overrides?.maxConcurrentRuns !== undefined) {
+        maxConcurrentRuns = options.overrides.maxConcurrentRuns;
+        maxConcurrentRunsExplicit = true;
+    }
+    let maxConcurrentRunsPerProject;
+    if (file.values.maxConcurrentRunsPerProject !== undefined) {
+        const n = coerceFileNumber(file.values.maxConcurrentRunsPerProject, "max_concurrent_runs_per_project");
+        if (!Number.isInteger(n) || n < 1) {
+            throw new HostConfigError(`Invalid value for max_concurrent_runs_per_project`, "config_invalid", "max_concurrent_runs_per_project");
+        }
+        maxConcurrentRunsPerProject = n;
+    }
+    if (env.STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT !== undefined) {
+        maxConcurrentRunsPerProject = parsePositiveInt(env.STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT, "STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT");
+    }
+    let maxQueued = DEFAULT_MAX_QUEUED;
+    if (file.values.maxQueued !== undefined) {
+        const n = coerceFileNumber(file.values.maxQueued, "max_queued");
+        if (!Number.isInteger(n) || n < 0) {
+            throw new HostConfigError(`Invalid value for max_queued`, "config_invalid", "max_queued");
+        }
+        maxQueued = n;
+    }
+    if (env.STAGEFLOW_MAX_QUEUED !== undefined) {
+        maxQueued = parsePositiveInt(env.STAGEFLOW_MAX_QUEUED, "STAGEFLOW_MAX_QUEUED", {
+            allowZero: true,
+        });
+    }
+    let requireProviders = [];
+    if (file.values.requireProviders !== undefined) {
+        requireProviders = coerceFileStringList(file.values.requireProviders, "require_providers");
+    }
+    if (env.STAGEFLOW_REQUIRE_PROVIDERS !== undefined) {
+        requireProviders = parseStringList(env.STAGEFLOW_REQUIRE_PROVIDERS);
+    }
+    let trustWorkspaceConfig = [];
+    if (file.values.trustWorkspaceConfig !== undefined) {
+        trustWorkspaceConfig = coerceFileStringList(file.values.trustWorkspaceConfig, "trust_workspace_config");
+    }
+    let allowUnknownFromFile = allowUnknownConfig;
+    if (file.values.allowUnknownConfig !== undefined) {
+        allowUnknownFromFile = coerceFileBool(file.values.allowUnknownConfig, "allow_unknown_config");
+    }
+    // Env already applied above for the unknown-key scan; file cannot enable after the fact.
+    void allowUnknownFromFile;
+    const controlToken = readSecretFromEnvOrFile(env, "STAGEFLOW_CONTROL_TOKEN");
+    const readToken = readSecretFromEnvOrFile(env, "STAGEFLOW_READ_TOKEN");
+    let callers = {};
+    if (file.values.callers !== undefined) {
+        callers = coerceCallers(file.values.callers, "callers");
+    }
+    let browserBlockedSites = [];
+    if (file.values.browser !== undefined) {
+        const raw = file.values.browser;
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new HostConfigError(`Invalid value for browser`, "config_invalid", "browser");
+        }
+        for (const sub of Object.keys(raw)) {
+            if (sub !== "blocked_sites") {
+                throw new HostConfigError(`Unknown key "${sub}" under browser`, "config_unknown_key", `browser.${sub}`);
+            }
+        }
+        const sites = raw.blocked_sites;
+        if (sites !== undefined) {
+            browserBlockedSites = coerceFileStringList(sites, "browser.blocked_sites")
+                .map((s) => s.trim().toLowerCase().replace(/^\*\./, "").replace(/^\./, ""))
+                .filter((s) => s.length > 0);
+            for (const site of browserBlockedSites) {
+                if (!/^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/.test(site)) {
+                    throw new HostConfigError(`Invalid domain "${site}" in browser.blocked_sites`, "config_invalid", "browser.blocked_sites");
+                }
+            }
+        }
+    }
+    return {
+        maxConcurrentRuns,
+        maxConcurrentRunsPerProject,
+        maxQueued,
+        requireProviders,
+        trustWorkspaceConfig,
+        allowUnknownConfig,
+        controlToken,
+        readToken,
+        callers,
+        browserBlockedSites,
+        configFilePath: configFilePath !== undefined && existsSync(configFilePath)
+            ? configFilePath
+            : undefined,
+        warnings,
+        maxConcurrentRunsExplicit,
+    };
+}
+export function redactHostConfig(config) {
+    return {
+        maxConcurrentRuns: config.maxConcurrentRuns,
+        maxConcurrentRunsPerProject: config.maxConcurrentRunsPerProject,
+        maxQueued: config.maxQueued,
+        requireProviders: [...config.requireProviders],
+        trustWorkspaceConfig: [...config.trustWorkspaceConfig],
+        allowUnknownConfig: config.allowUnknownConfig,
+        callers: { ...config.callers },
+        secrets: {
+            controlToken: config.controlToken ? "set" : "unset",
+            readToken: config.readToken ? "set" : "unset",
+        },
+    };
+}

package/dist/config/listSkills.d.ts

@@ -1,4 +1,6 @@
 export type SkillScope = "user" | "project" | "temporary";
+/** Skill resolution origin — separate from ConfigOriginKind. */
+export type SkillOrigin = "run" | "checkout" | "host" | "builtin";
 export type SkillListing = {
     name: string;
     description: string;
@@ -7,6 +9,7 @@ export type SkillListing = {
     scope: SkillScope;
     source: string;
     disableModelInvocation: boolean;
+    origin?: SkillOrigin;
 };
 export type SkillDiagnostic = {
     message: string;
@@ -19,11 +22,34 @@ export type SkillCatalog = {
 export type ListSkillsOptions = {
     cwd: string;
     agentDir: string;
+    /** Materialized run skills root: `$STAGEFLOW_HOME/runs/<runId>/skills`. */
+    runSkillsDir?: string;
+    /** Checkout / worktree root whose `.pi/skills` is the checkout tier. */
+    checkoutRoot?: string;
 };
 export type ResolvedSkill = {
     name: string;
     filePath: string;
     baseDir: string;
+    scope: SkillScope;
+    source: string;
+    origin: SkillOrigin;
+};
+export type SkillOriginListing = {
+    name: string;
+    description: string;
+    origin: SkillOrigin;
 };
+/**
+ * Resolve a skill by name. Search order: run skills → checkout `.pi/skills` → host agentDir → package built-ins.
+ */
 export declare function resolveSkillByName(name: string, options: ListSkillsOptions): Promise<ResolvedSkill | undefined>;
 export declare function listSkills(options: ListSkillsOptions): Promise<SkillCatalog>;
+/**
+ * List skills with SkillOrigin. When runSkillsDir is set, run-tier skills win on name.
+ * Precedence for the merged view: run → checkout → host.
+ */
+export declare function listSkillsWithOrigin(options: ListSkillsOptions): Promise<{
+    skills: SkillOriginListing[];
+    diagnostics: SkillDiagnostic[];
+}>;

package/dist/config/listSkills.js

@@ -1,6 +1,8 @@
-import { access } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveBuiltinSkillFile } from "./builtinSkills.js";
 import { DefaultResourceLoader, SettingsManager, } from "@earendil-works/pi-coding-agent";
-function toListing(skill) {
+function toListing(skill, origin) {
     return {
         name: skill.name,
         description: skill.description,
@@ -9,8 +11,39 @@ function toListing(skill) {
         scope: skill.sourceInfo.scope,
         source: skill.sourceInfo.source,
         disableModelInvocation: skill.disableModelInvocation,
+        ...(origin !== undefined ? { origin } : {}),
     };
 }
+function isUnderRoot(candidate, root) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(candidate);
+    const rel = path.relative(resolvedRoot, resolved);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function descriptionFromSkillMd(content) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+    if (!match)
+        return undefined;
+    const block = match[1];
+    const descLine = /^description:\s*(.*)$/m.exec(block);
+    if (!descLine)
+        return undefined;
+    let value = descLine[1].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return value.length > 0 ? value : undefined;
+}
 async function openSkillCatalogLoader(options) {
     const settingsManager = SettingsManager.create(options.cwd, options.agentDir, {
         projectTrusted: true,
@@ -23,21 +56,108 @@ async function openSkillCatalogLoader(options) {
     await loader.reload();
     return loader;
 }
+async function resolveRunSkill(name, runSkillsDir) {
+    if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+        return undefined;
+    }
+    const baseDir = path.join(runSkillsDir, name);
+    const filePath = path.join(baseDir, "SKILL.md");
+    if (!(await pathExists(filePath)))
+        return undefined;
+    return {
+        name,
+        filePath,
+        baseDir,
+        scope: "temporary",
+        source: "run",
+        origin: "run",
+    };
+}
+async function resolveCheckoutSkill(name, checkoutRoot) {
+    if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+        return undefined;
+    }
+    const baseDir = path.join(checkoutRoot, ".pi", "skills", name);
+    const filePath = path.join(baseDir, "SKILL.md");
+    if (!(await pathExists(filePath)))
+        return undefined;
+    return {
+        name,
+        filePath,
+        baseDir,
+        scope: "project",
+        source: "checkout",
+        origin: "checkout",
+    };
+}
+function originForLoaderSkill(skill, options) {
+    if (options.checkoutRoot !== undefined &&
+        isUnderRoot(skill.filePath, path.join(options.checkoutRoot, ".pi", "skills"))) {
+        return "checkout";
+    }
+    if (isUnderRoot(skill.filePath, path.join(options.agentDir, "skills"))) {
+        return "host";
+    }
+    if (skill.sourceInfo.scope === "project") {
+        return "checkout";
+    }
+    return "host";
+}
+function resolveBuiltinResolved(name) {
+    const filePath = resolveBuiltinSkillFile(name);
+    if (filePath === undefined)
+        return undefined;
+    return {
+        name,
+        filePath,
+        baseDir: path.dirname(filePath),
+        scope: "user",
+        source: "builtin",
+        origin: "builtin",
+    };
+}
+/**
+ * Resolve a skill by name. Search order: run skills → checkout `.pi/skills` → host agentDir → package built-ins.
+ */
 export async function resolveSkillByName(name, options) {
+    if (options.runSkillsDir !== undefined) {
+        const run = await resolveRunSkill(name, options.runSkillsDir);
+        if (run)
+            return run;
+    }
+    if (options.checkoutRoot !== undefined) {
+        const checkout = await resolveCheckoutSkill(name, options.checkoutRoot);
+        if (checkout)
+            return checkout;
+    }
     const loader = await openSkillCatalogLoader(options);
     const match = loader.getSkills().skills.find((skill) => skill.name === name);
     if (!match)
-        return undefined;
+        return resolveBuiltinResolved(name);
     try {
         await access(match.filePath);
     }
     catch {
-        return undefined;
+        return resolveBuiltinResolved(name);
+    }
+    if (options.checkoutRoot !== undefined &&
+        isUnderRoot(match.filePath, path.join(options.checkoutRoot, ".pi", "skills"))) {
+        return {
+            name: match.name,
+            filePath: match.filePath,
+            baseDir: match.baseDir,
+            scope: match.sourceInfo.scope,
+            source: match.sourceInfo.source,
+            origin: "checkout",
+        };
     }
     return {
         name: match.name,
         filePath: match.filePath,
         baseDir: match.baseDir,
+        scope: match.sourceInfo.scope,
+        source: match.sourceInfo.source,
+        origin: originForLoaderSkill(match, options),
     };
 }
 export async function listSkills(options) {
@@ -45,7 +165,7 @@ export async function listSkills(options) {
     const { skills, diagnostics } = loader.getSkills();
     return {
         skills: skills
-            .map(toListing)
+            .map((skill) => toListing(skill, originForLoaderSkill(skill, options)))
             .sort((a, b) => a.name.localeCompare(b.name)),
         diagnostics: diagnostics.map((d) => ({
             message: d.message,
@@ -53,3 +173,84 @@ export async function listSkills(options) {
         })),
     };
 }
+async function listRunSkillOrigins(runSkillsDir) {
+    let names;
+    try {
+        names = await readdir(runSkillsDir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+            continue;
+        }
+        const filePath = path.join(runSkillsDir, name, "SKILL.md");
+        try {
+            const content = await readFile(filePath, "utf8");
+            const description = descriptionFromSkillMd(content);
+            if (description === undefined)
+                continue;
+            out.push({ name, description, origin: "run" });
+        }
+        catch {
+            // skip unreadable / incomplete packs
+        }
+    }
+    return out;
+}
+/**
+ * List skills with SkillOrigin. When runSkillsDir is set, run-tier skills win on name.
+ * Precedence for the merged view: run → checkout → host.
+ */
+export async function listSkillsWithOrigin(options) {
+    const byName = new Map();
+    const hostCatalog = await listSkills({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        ...(options.checkoutRoot !== undefined
+            ? { checkoutRoot: options.checkoutRoot }
+            : {}),
+    });
+    for (const skill of hostCatalog.skills) {
+        const origin = skill.origin ??
+            (skill.scope === "project" ? "checkout" : "host");
+        byName.set(skill.name, {
+            name: skill.name,
+            description: skill.description,
+            origin,
+        });
+    }
+    if (options.checkoutRoot !== undefined) {
+        let checkoutNames = [];
+        try {
+            checkoutNames = await readdir(path.join(options.checkoutRoot, ".pi", "skills"));
+        }
+        catch {
+            checkoutNames = [];
+        }
+        for (const name of checkoutNames) {
+            const filePath = path.join(options.checkoutRoot, ".pi", "skills", name, "SKILL.md");
+            try {
+                const content = await readFile(filePath, "utf8");
+                const description = descriptionFromSkillMd(content);
+                if (description === undefined)
+                    continue;
+                byName.set(name, { name, description, origin: "checkout" });
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    if (options.runSkillsDir !== undefined) {
+        for (const skill of await listRunSkillOrigins(options.runSkillsDir)) {
+            byName.set(skill.name, skill);
+        }
+    }
+    return {
+        skills: [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        diagnostics: hostCatalog.diagnostics,
+    };
+}

package/dist/config/loadOutcome.d.ts

@@ -1,5 +1,6 @@
 import type { ValidationFindingCode } from "./validateCatalog.js";
-export type TaskLoadCode = "task.invalid_shape" | "task.load_error";
+export type TaskLoadCode = "task.invalid_shape" | "task.load_error" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid";
+export type TriggerLoadCode = "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task";
 export type LoadIssue = {
     code: ValidationFindingCode;
     message: string;
@@ -16,6 +17,11 @@ export type LoadIssue = {
     message: string;
     category: "task";
     taskId?: string;
+} | {
+    code: TriggerLoadCode;
+    message: string;
+    category: "trigger";
+    triggerId?: string;
 } | {
     code: ValidationFindingCode | string;
     message: string;