stageflow 0.25.0 → 0.27.0

package/dist/config/hostConfig.d.ts

@@ -0,0 +1,55 @@
+export declare class HostConfigError extends Error {
+    readonly code: "config_unknown_key" | "config_invalid";
+    readonly key?: string;
+    constructor(message: string, code: "config_unknown_key" | "config_invalid", key?: string);
+}
+/** Env keys that are known STAGEFLOW_* (or dynamic families) so unknown-key check accepts them. */
+export declare const KNOWN_STAGEFLOW_ENV_KEYS: Set<string>;
+/** Per-caller concurrent-active quota from host `callers:` config. */
+export type CallerQuotaConfig = {
+    maxConcurrent: number;
+};
+export type HostConfig = {
+    maxConcurrentRuns: number;
+    maxConcurrentRunsPerProject: number | undefined;
+    maxQueued: number;
+    requireProviders: string[];
+    trustWorkspaceConfig: string[];
+    allowUnknownConfig: boolean;
+    controlToken: string | undefined;
+    readToken: string | undefined;
+    /** caller_id → quota; empty when unset. */
+    callers: Record<string, CallerQuotaConfig>;
+    /** Absolute path of config.yaml when loaded; undefined if absent. */
+    configFilePath: string | undefined;
+    warnings: string[];
+    /** True when maxConcurrentRuns came from override, env, or file (not bare default). */
+    maxConcurrentRunsExplicit: boolean;
+};
+export type HostConfigOverrides = {
+    maxConcurrentRuns?: number;
+};
+export type HostConfigSecretsEcho = {
+    controlToken: "set" | "unset";
+    readToken: "set" | "unset";
+};
+export type HostConfigPublicEcho = {
+    maxConcurrentRuns: number;
+    maxConcurrentRunsPerProject: number | undefined;
+    maxQueued: number;
+    requireProviders: string[];
+    trustWorkspaceConfig: string[];
+    allowUnknownConfig: boolean;
+    callers: Record<string, CallerQuotaConfig>;
+    secrets: HostConfigSecretsEcho;
+};
+/**
+ * Assemble HostConfig once at boot. Precedence: overrides (CLI flags) > env > file > default.
+ */
+export declare function loadHostConfig(options?: {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    overrides?: HostConfigOverrides;
+    configFilePath?: string | null;
+}): HostConfig;
+export declare function redactHostConfig(config: HostConfig): HostConfigPublicEcho;

package/dist/config/hostConfig.js

@@ -0,0 +1,333 @@
+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",
+]);
+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",
+};
+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");
+    }
+    return {
+        maxConcurrentRuns,
+        maxConcurrentRunsPerProject,
+        maxQueued,
+        requireProviders,
+        trustWorkspaceConfig,
+        allowUnknownConfig,
+        controlToken,
+        readToken,
+        callers,
+        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";
 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.
+ */
 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,7 @@
-import { access } from "node:fs/promises";
+import { access, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
 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 +10,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,7 +55,67 @@ 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";
+}
+/**
+ * Resolve a skill by name. Search order: run skills → checkout `.pi/skills` → host agentDir.
+ */
 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)
@@ -34,10 +126,24 @@ export async function resolveSkillByName(name, options) {
     catch {
         return undefined;
     }
+    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 +151,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 +159,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,5 @@
 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 LoadIssue = {
     code: ValidationFindingCode;
     message: string;