@hcflabs/pi-subagent 0.0.0-stage → 27.10.8

package/dist/index.js

@@ -0,0 +1,589 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DefaultPackageManager, getAgentDir, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createConfigStore, extensionConfigDir, field, formatConfigIssues, parsers, registerConfigReporting } from "@hcflabs/pi-config-store";
+import { hasDisplayControlCharacters } from "./display-text.js";
+import { DEFAULT_MAX_TURNS } from "./ephemeral.js";
+import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
+import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@hcflabs/pi-task-models";
+export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
+export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
+export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
+export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, } from "./worktree.js";
+export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
+const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
+const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@hcflabs/pi-multi-codex/extensions/multi-codex.ts"));
+const ROLE_MCP_EXTENSION = fileURLToPath(new URL("../extensions/role-mcp.ts", import.meta.url));
+const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
+const GIT_READ_EXTENSION = fileURLToPath(new URL("../extensions/git-read.ts", import.meta.url));
+export { PI_SUBAGENT_PROCESS_LEASE } from "./process-lease.js";
+export const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
+export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+const CODEMODE_TOOL = "codemode";
+/** The value after a flag that must appear exactly once in a child's argv. */
+function flagValueFromArgv(args, flag) {
+    const indexes = args.flatMap((arg, index) => arg === flag ? [index] : []);
+    if (indexes.length !== 1)
+        throw new Error(`${flag} must appear exactly once.`);
+    return args[indexes[0] + 1];
+}
+/** Read child MCP policy before Pi binds registered extension flag values. */
+export function roleMcpAllowlistFromArgv(args) {
+    return parseRoleMcpAllowlist(flagValueFromArgv(args, `--${ROLE_MCP_POLICY_FLAG}`));
+}
+/** Parse the Role tool policy flag value: JSON tool names. */
+export function parseRoleToolPolicy(value) {
+    if (typeof value !== "string")
+        throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((name) => typeof name !== "string" || !name.trim() || name.includes("\0"))) {
+        throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
+    }
+    return [...new Set(parsed.map((name) => name.trim()))];
+}
+/** Read child tool policy before Pi binds registered extension flag values. */
+export function roleToolPolicyFromArgv(args) {
+    return parseRoleToolPolicy(flagValueFromArgv(args, `--${ROLE_TOOL_POLICY_FLAG}`));
+}
+/**
+ * Whether a tool policy activates `codemode` in the child, so scripts can reach tools with
+ * `codemode` or `deferred` exposure. Loading `builtin:codemode` alone registers the tool inactive.
+ */
+export function roleActivatesCodemode(tools) {
+    return tools.includes(CODEMODE_TOOL);
+}
+export const CHILD_EXCLUDED_TOOL_NAMES = [
+    "delegate_task",
+    "ask_question",
+    "subagent_status",
+    "subagent_resume",
+    "subagent_stage",
+    "subagent_integrate",
+    "subagent_abort",
+    "herdr_handoff",
+];
+const SYSTEM_PROMPT_FLAG = "--append-system-prompt";
+const CHILD_IDENTITY_POLICY = "You are a delegated Pi Subagent, not Main. Execute the assigned Role and task directly. Main-only delegation rules do not apply. Recursive delegation is unavailable; do not seek or invoke delegation tools.";
+export const DELEGATE_TASK = {
+    id: "pi-subagent/delegateTask",
+    label: "Subagent delegation",
+    purpose: "Launch direct or checked isolated Pi delegation.",
+    defaultProfile: "fast",
+};
+const cleanText = (value, field, source) => {
+    if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
+        throw new Error(`${source}: ${field} must be non-empty text.`);
+    }
+    return value.trim();
+};
+const cleanDisplayText = (value, field, source) => {
+    if (typeof value === "string" && hasDisplayControlCharacters(value)) {
+        throw new Error(`${source}: ${field} must not contain C0/C1 control characters.`);
+    }
+    return cleanText(value, field, source);
+};
+/** Normalize one arbitrary Role name using the Role configuration contract. */
+export function parseRoleName(value, source = "Role") {
+    return cleanDisplayText(value, "name", source);
+}
+const stringList = (value, field, source) => {
+    if (value === undefined)
+        throw new Error(`${source}: ${field} is required.`);
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
+        throw new Error(`${source}: ${field} must be an array of strings.`);
+    }
+    return value.map((item) => item.trim());
+};
+// Pi built-in extensions (`builtin:<name>`, see Pi's settings docs); Pi exports no list of them.
+// `builtin:mcp` is excluded: it connects every server in mcp.json and would bypass the Role `mcps` allowlist.
+const BUILTIN_EXTENSION_NAMES = ["codemode", "tool-search", "llama.cpp"];
+const BUILTIN_EXTENSION_PREFIX = "builtin:";
+function validateExtension(extension, source) {
+    const value = cleanText(extension, "extension", source);
+    if (value.startsWith(BUILTIN_EXTENSION_PREFIX)) {
+        if (value === `${BUILTIN_EXTENSION_PREFIX}mcp`) {
+            throw new Error(`${source} must select MCP servers with mcps instead of loading builtin:mcp directly.`);
+        }
+        if (!BUILTIN_EXTENSION_NAMES.includes(value.slice(BUILTIN_EXTENSION_PREFIX.length))) {
+            throw new Error(`${source}: unknown built-in extension ${value}; use ${BUILTIN_EXTENSION_NAMES.map((name) => `${BUILTIN_EXTENSION_PREFIX}${name}`).join(", ")}.`);
+        }
+        return value;
+    }
+    const packageSource = /^(?:npm|git|github|https?|ssh):/.test(value);
+    const userPath = isAbsolute(value) || value.startsWith("~/") || value.startsWith("~\\") || value.startsWith("file://");
+    if (!packageSource && !userPath) {
+        throw new Error(`${source}: extensions entries must be absolute paths, package sources, or builtin:<name>.`);
+    }
+    return value;
+}
+function extensionList(value, source) {
+    return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
+}
+function mcpList(value, source) {
+    const names = stringList(value ?? [], "mcps", source);
+    if (new Set(names).size !== names.length)
+        throw new Error(`${source}: mcps contains duplicate MCP server names.`);
+    return names;
+}
+function roleToolPolicy(role, additionalTools = []) {
+    return [...new Set([...role.tools, ...additionalTools].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+}
+function namesMcpAdapter(extension) {
+    return extension.toLowerCase().split(/[\\/:@]+/).some((component) => component === "pi-mcp-adapter" || component.startsWith("pi-mcp-adapter."));
+}
+const FORBIDDEN_ROLE_PACKAGE_SOURCE_NAMES = ["pi-subagent", "pi-mcp-adapter"];
+function rejectForbiddenRolePackageSource(value, role) {
+    const components = value.toLowerCase().split(/[\\/:@]+/);
+    if (FORBIDDEN_ROLE_PACKAGE_SOURCE_NAMES.some((name) => components.some((component) => component === name || component.startsWith(`${name}.`)))) {
+        throw new Error(`Role ${role.name} extension explicitly names the forbidden ${FORBIDDEN_ROLE_PACKAGE_SOURCE_NAMES.join("/")} source: ${value}`);
+    }
+}
+function roleModelClass(value, source) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string" || !PROFILE_NAMES.includes(value)) {
+        throw new Error(`${source}: modelClass must be one of ${PROFILE_NAMES.join(", ")}.`);
+    }
+    return value;
+}
+function rejectRetiredRoleIsolation(value, source) {
+    if (value === undefined)
+        return;
+    throw new Error(`${source}: Role isolation is retired; select mode \"isolated\" on delegate_task instead.`);
+}
+const ROLE_FRONTMATTER_KEYS = ["name", "description", "modelClass", "tools", "extensions", "skills", "mcps"];
+const ROLE_DEFAULT_KEYS = ["extensions", "tools", "skills"];
+/** Validate `config.json` `roleDefaults` with the same rules as Role fields; `label` prefixes errors. */
+export function parseRoleDefaults(value, label = "roleDefaults") {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be a JSON object.`);
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!ROLE_DEFAULT_KEYS.includes(key))
+            throw new Error(`${label}: unknown key ${JSON.stringify(key)}; expected ${ROLE_DEFAULT_KEYS.join(", ")}.`);
+    }
+    return {
+        ...(record.extensions === undefined ? {} : { extensions: extensionList(record.extensions, label) }),
+        ...(record.tools === undefined ? {} : { tools: stringList(record.tools, "tools", label) }),
+        ...(record.skills === undefined ? {} : { skills: stringList(record.skills, "skills", label) }),
+    };
+}
+/** Per-key `roleDefaults`: an unknown key or invalid list is reported and dropped, so fewer resources load. */
+const roleDefaultsField = (raw, report) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("must be a JSON object");
+    const defaults = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!ROLE_DEFAULT_KEYS.includes(key)) {
+            report([key], "unknown key", "unknown-key");
+            continue;
+        }
+        try {
+            Object.assign(defaults, parseRoleDefaults({ [key]: value }));
+        }
+        catch (error) {
+            report([key], error instanceof Error ? error.message : String(error));
+        }
+    }
+    return defaults;
+};
+export const DEFAULT_SUBAGENT_CONFIG = Object.freeze({
+    maxSubagents: 5,
+    maxTurns: DEFAULT_MAX_TURNS,
+    maxTokens: undefined,
+    maxCorrections: 1,
+    timeout: Object.freeze({ idleMinutes: 10, maxMinutes: 30 }),
+    roleDefaults: Object.freeze({}),
+});
+const timeoutMinutes = parsers.number({ greaterThan: 0, max: 2_147_483_647 / 60_000 });
+const timeoutField = (raw, report) => {
+    const timeout = parsers.object({
+        idleMinutes: field(timeoutMinutes, DEFAULT_SUBAGENT_CONFIG.timeout.idleMinutes),
+        maxMinutes: field(timeoutMinutes, DEFAULT_SUBAGENT_CONFIG.timeout.maxMinutes),
+    })(raw, report);
+    if (timeout.maxMinutes <= timeout.idleMinutes) {
+        throw new Error(`maxMinutes (${timeout.maxMinutes}) must be greater than idleMinutes (${timeout.idleMinutes})`);
+    }
+    return timeout;
+};
+/**
+ * The user `config.json` store shared by the extension and `loadRoleCatalog`.
+ * Invalid bounded limits and `roleDefaults` keys fall back to defaults; an
+ * invalid `maxTokens` disables the config because its default is unlimited.
+ */
+export function createSubagentConfigStore(agentDir = getAgentDir()) {
+    return createConfigStore({
+        extensionId: "pi-subagent",
+        agentDir,
+        fields: {
+            maxSubagents: field(parsers.integer({ min: 1 }), DEFAULT_SUBAGENT_CONFIG.maxSubagents),
+            maxTurns: field(parsers.integer({ min: 1 }), DEFAULT_SUBAGENT_CONFIG.maxTurns),
+            maxTokens: field(parsers.integer({ min: 1 }), undefined, { onInvalid: "disable" }),
+            maxCorrections: field(parsers.integer({ min: 0 }), DEFAULT_SUBAGENT_CONFIG.maxCorrections),
+            timeout: field(timeoutField, DEFAULT_SUBAGENT_CONFIG.timeout),
+            roleDefaults: field(roleDefaultsField, DEFAULT_SUBAGENT_CONFIG.roleDefaults),
+        },
+    });
+}
+/**
+ * Read only `roleDefaults`. The extension reports and enforces the execution limits, so a bad limit does not
+ * break the Role catalog of other consumers; other keys are not this reader's issues.
+ */
+function loadRoleDefaults(agentDir) {
+    const store = createConfigStore({
+        extensionId: "pi-subagent",
+        agentDir,
+        fields: { roleDefaults: field(roleDefaultsField, DEFAULT_SUBAGENT_CONFIG.roleDefaults) },
+    });
+    const loaded = store.loadSync();
+    const issues = loaded.issues.filter(({ key }) => !key || /^roleDefaults(?![\w$])/.test(key));
+    // A file that cannot load has no trusted `roleDefaults`.
+    return issues.some(({ key }) => !key)
+        ? { store, loaded: { status: "disabled", source: loaded.source, issues } }
+        : { store, loaded: { ...loaded, issues } };
+}
+function readRoleDefaults(agentDir) {
+    const { store, loaded } = loadRoleDefaults(agentDir);
+    if (loaded.status !== "ok")
+        throw new Error(`${store.path}: ${formatConfigIssues(loaded.issues)}`);
+    return loaded.value.roleDefaults;
+}
+/**
+ * Report `roleDefaults` issues at each session start, and return a function that reports them after a lazy
+ * Role catalog load, such as `loadRoleCatalog` or `resolveRoleLaunch`. Every pi-config-store reporter shares
+ * one record, so each issue shows one time in each session, also with the pi-subagent extension active.
+ */
+export function registerRoleDefaultsReporting(pi, agentDir = getAgentDir()) {
+    const target = loadRoleDefaults(agentDir).store;
+    const reporter = registerConfigReporting(pi, []);
+    const report = (ctx) => reporter.report(ctx, target, loadRoleDefaults(agentDir).loaded);
+    pi.on("session_start", (_event, ctx) => report(ctx));
+    return report;
+}
+const withDefaults = (defaults, values) => [...new Set([...(defaults ?? []), ...values])];
+function applyRoleDefaults(role, defaults) {
+    return {
+        ...role,
+        tools: withDefaults(defaults.tools, role.tools),
+        extensions: withDefaults(defaults.extensions, role.extensions),
+        skills: withDefaults(defaults.skills, role.skills),
+    };
+}
+// Built-in Roles resolved from the package-shipped Markdown relative to this module.
+const BUILTIN_ROLE_NAMES = ["implementer", "reviewer", "scout"];
+/** Single-file Role parser shared by built-in and user roles. */
+function parseRoleFile(file, raw) {
+    let parsed;
+    try {
+        parsed = parseFrontmatter(raw);
+    }
+    catch (error) {
+        throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const frontmatter = parsed.frontmatter;
+    rejectRetiredRoleIsolation(frontmatter.isolation, file);
+    for (const key of Object.keys(frontmatter)) {
+        if (!ROLE_FRONTMATTER_KEYS.includes(key)) {
+            throw new Error(`${file}: unknown Role frontmatter key ${JSON.stringify(key)}; expected ${ROLE_FRONTMATTER_KEYS.join(", ")}.`);
+        }
+    }
+    const modelClass = roleModelClass(frontmatter.modelClass, file);
+    return {
+        name: parseRoleName(frontmatter.name, file),
+        description: cleanDisplayText(frontmatter.description, "description", file),
+        ...(modelClass === undefined ? {} : { modelClass }),
+        tools: stringList(frontmatter.tools, "tools", file),
+        extensions: extensionList(frontmatter.extensions, file),
+        skills: stringList(frontmatter.skills, "skills", file),
+        mcps: mcpList(frontmatter.mcps, file),
+        systemPrompt: cleanText(parsed.body, "system prompt", file),
+    };
+}
+function readRoleFile(file) {
+    try {
+        return parseRoleFile(file, readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(`${file}: `))
+            throw error;
+        throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function loadBuiltinRole(name) {
+    return readRoleFile(fileURLToPath(new URL(`../examples/roles/${name}.md`, import.meta.url)));
+}
+function builtinRoles() {
+    return BUILTIN_ROLE_NAMES.map(loadBuiltinRole);
+}
+function claimedRoleName(file) {
+    try {
+        const { name } = parseFrontmatter(readFileSync(file, "utf8")).frontmatter;
+        if (typeof name === "string" && name.trim())
+            return name.trim();
+    }
+    catch { /* The file's own error is reported; fall back to its stem. */ }
+    return basename(file, ".md");
+}
+/**
+ * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
+ * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
+ * invalid or duplicate user file is reported and makes its claimed name
+ * unavailable without hiding valid Roles. Invalid `roleDefaults` keys are
+ * dropped; a `config.json` that cannot load (for example, malformed JSON) throws.
+ */
+export function loadRoleCatalog(agentDir = getAgentDir()) {
+    const defaults = readRoleDefaults(agentDir);
+    const builtins = new Map(builtinRoles().map((role) => [role.name, role]));
+    const dir = extensionConfigDir("pi-subagent", agentDir);
+    let entries = [];
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    const user = new Map();
+    const errors = [];
+    for (const entry of entries
+        .filter((candidate) => candidate.name.endsWith(".md") && (candidate.isFile() || candidate.isSymbolicLink()))
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = join(dir, entry.name);
+        try {
+            const role = readRoleFile(file);
+            user.set(role.name, [...(user.get(role.name) ?? []), { file, role }]);
+        }
+        catch (error) {
+            errors.push({ file, name: claimedRoleName(file), message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    for (const [name, files] of user) {
+        if (files.length < 2)
+            continue;
+        for (const { file } of files)
+            errors.push({ file, name, message: `${file}: Duplicate Subagent role: ${name} (${files.map((item) => item.file).join(", ")}).` });
+    }
+    const blocked = new Set(errors.map(({ name }) => name));
+    const sources = new Map();
+    const byName = new Map();
+    for (const [name, role] of builtins) {
+        byName.set(name, user.get(name)?.[0]?.role ?? role);
+        sources.set(name, user.has(name) ? "user override" : "built-in");
+    }
+    for (const [name, files] of user) {
+        if (builtins.has(name))
+            continue;
+        byName.set(name, files[0].role);
+        sources.set(name, "user");
+    }
+    for (const name of blocked) {
+        byName.delete(name);
+        sources.delete(name);
+    }
+    return { roles: [...byName.values()].map((role) => applyRoleDefaults(role, defaults)), sources, errors };
+}
+/** Select one catalog Role, naming invalid files that claim it. */
+export function findRole(catalog, name) {
+    const role = catalog.roles.find((candidate) => candidate.name === name);
+    if (role)
+        return role;
+    const invalid = catalog.errors.filter((error) => error.name === name);
+    if (invalid.length)
+        throw new Error(`Subagent role ${name} is unavailable: ${invalid.map(({ message }) => message).join("; ")}`);
+    throw new Error(`Unknown Subagent role: ${name}. Available roles: ${catalog.roles.map((candidate) => candidate.name).join(", ") || "none"}.${catalog.errors.length ? ` ${catalog.errors.length} invalid Role file(s); run /subagent roles.` : ""}`);
+}
+export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
+    // A disabled config throws with the path and the problems.
+    const config = loadTaskModelsConfig(agentDir).value;
+    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName]);
+}
+function resolveConfiguredRoute(ctx, profileName, profile) {
+    if (!profile)
+        throw new Error(`No ${profileName} task model profile is configured. Run /task-models.`);
+    for (const route of orderedProfileRoutes(profile)) {
+        const resolved = resolveTaskModelRoute(ctx, route);
+        if (resolved)
+            return resolved;
+    }
+    throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
+}
+export function resolveRoleSkills(pi, role) {
+    const skills = new Map(pi.getCommands()
+        .filter((command) => command.source === "skill")
+        .map((command) => [command.name, command.sourceInfo.path]));
+    const paths = [];
+    const missing = [];
+    for (const name of role.skills) {
+        const path = skills.get(`skill:${name}`);
+        if (path)
+            paths.push(path);
+        else
+            missing.push(name);
+    }
+    return { paths, missing };
+}
+function packageManager(ctx) {
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(ctx.cwd, agentDir, { projectTrusted: ctx.isProjectTrusted() });
+    return new DefaultPackageManager({ cwd: ctx.cwd, agentDir, settingsManager });
+}
+/** Resolve all enabled package resources selected by one Role's extension sources. */
+export async function resolveRolePackageResources(role, ctx) {
+    const sources = role.extensions;
+    for (const source of sources)
+        rejectForbiddenRolePackageSource(source, role);
+    if (!sources.length)
+        return { extensions: [], skills: [], prompts: [], themes: [] };
+    const resolved = await packageManager(ctx).resolveExtensionSources([...sources]);
+    const resourceGroups = [resolved.extensions, resolved.skills, resolved.prompts, resolved.themes]
+        .map((resources) => resources.filter((resource) => resource.enabled));
+    // Built-in extensions resolve to their `builtin:<name>` path with the bare source `builtin`.
+    const resolvedSources = new Set(resourceGroups.flat()
+        .map((resource) => resource.metadata.source === "builtin" ? resource.path : resource.metadata.source));
+    const missing = sources.filter((source) => !resolvedSources.has(source));
+    if (missing.length)
+        throw new Error(`Role extension sources resolved no resources: ${missing.join(", ")}.`);
+    return {
+        extensions: resourceGroups[0].map((resource) => resource.path),
+        skills: resourceGroups[1].map((resource) => resource.path),
+        prompts: resourceGroups[2].map((resource) => resource.path),
+        themes: resourceGroups[3].map((resource) => resource.path),
+    };
+}
+export function createRoleLaunch(pi, ctx, input) {
+    return finalizeRoleLaunch(prepareRoleLaunchFromSkills(ctx, input, resolveRoleSkills(pi, input.role)));
+}
+/** Build the prompt-free argv and tool policy; the Role prompt stays separate until `finalizeRoleLaunch`. */
+function prepareRoleLaunchFromSkills(ctx, input, skills) {
+    const role = input.role;
+    const mcps = mcpList(role.mcps, `Role ${role.name}`);
+    const tools = roleToolPolicy(role, input.tools);
+    const selectedExtensions = [...role.extensions, ...(input.extensions ?? [])]
+        .map((extension) => validateExtension(extension, `Role ${role.name}`));
+    if (selectedExtensions.some(namesMcpAdapter)) {
+        throw new Error(`Role ${role.name} must select MCP servers with mcps instead of loading pi-mcp-adapter directly.`);
+    }
+    const extensions = [
+        ...selectedExtensions,
+        ...(CODEX_ALIAS.test(input.route.model.provider) ? [MULTI_CODEX_EXTENSION] : []),
+        // Always loaded: it connects the servers that Role extensions register; `mcps` gates only mcp.json.
+        ROLE_MCP_EXTENSION,
+        ...(role.tools.includes("git_read") ? [GIT_READ_EXTENSION] : []),
+        ROLE_TOOLS_EXTENSION,
+    ];
+    const env = Object.fromEntries(Object.entries(input.env ?? {}).map(([key, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            throw new Error(`Invalid launch environment name: ${key}`);
+        if (typeof value !== "string" || value.includes("\0"))
+            throw new Error(`Invalid launch environment value: ${key}`);
+        return [key, value];
+    }));
+    const args = ["--no-session", "--no-extensions", "--no-skills", "--exclude-tools", CHILD_EXCLUDED_TOOL_NAMES.join(",")];
+    args.push(`--${ROLE_MCP_POLICY_FLAG}`, JSON.stringify(mcps));
+    for (const extension of new Set(extensions))
+        args.push("--extension", extension);
+    for (const skill of skills.paths)
+        args.push("--skill", skill);
+    args.push(`--${ROLE_TOOL_POLICY_FLAG}`, JSON.stringify(tools));
+    args.push("--model", modelReference(input.route.model));
+    if (input.route.thinkingLevel)
+        args.push("--thinking", input.route.thinkingLevel);
+    args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
+    return {
+        env,
+        args,
+        model: input.route.model,
+        thinkingLevel: input.route.thinkingLevel,
+        missingSkills: skills.missing,
+        role: role.name,
+        tools: Object.freeze(tools),
+        systemPrompt: `${CHILD_IDENTITY_POLICY}\n\n${cleanText(role.systemPrompt, "system prompt", `Role ${role.name}`)}`,
+        promptArgIndex: args.length,
+    };
+}
+function prepareResolvedRoleLaunch(pi, ctx, input) {
+    const { task, modelClass, agentDir, ...launchInput } = input;
+    const selectedClass = modelClass ?? input.role.modelClass;
+    return prepareRoleLaunchFromSkills(ctx, {
+        ...launchInput,
+        route: selectedClass === undefined
+            ? resolveConfiguredTaskRoute(ctx, task, agentDir)
+            : resolveTaskRoute(ctx, selectedClass, agentDir),
+    }, resolveRoleSkills(pi, input.role));
+}
+export function resolveRoleLaunch(pi, ctx, input) {
+    return finalizeRoleLaunch(prepareResolvedRoleLaunch(pi, ctx, input));
+}
+function assertNoMissingRoleSkills(role, launch) {
+    if (!launch.missingSkills.length)
+        return;
+    throw new Error(`Role ${parseRoleName(role.name)} requires missing Skills: ${launch.missingSkills.join(", ")}.`);
+}
+export function prepareRoleLaunch(pi, ctx, input) {
+    const role = parseRoleName(input.role.name);
+    rejectRetiredRoleIsolation(input.role.isolation, `Role ${role}`);
+    const prepared = "route" in input
+        ? prepareRoleLaunchFromSkills(ctx, input, resolveRoleSkills(pi, input.role))
+        : prepareResolvedRoleLaunch(pi, ctx, input);
+    assertNoMissingRoleSkills(input.role, prepared);
+    // Validate the mcp.json the child reads: its environment inherits Main's, with launch overrides on top.
+    if (input.role.mcps?.length) {
+        loadRoleMcpConfig(prepared.env.PI_CODING_AGENT_DIR ?? getAgentDir(), input.role.mcps, { codemode: roleActivatesCodemode(prepared.tools) });
+    }
+    return { ...prepared, role };
+}
+/** Resolve and prepare a configured Role with its package-owned resources. */
+export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
+    const roleName = parseRoleName(input.role);
+    if (input.modelClass === undefined)
+        throw new Error("Configured Role launch requires an explicit modelClass.");
+    const role = findRole(loadRoleCatalog(), roleName);
+    if (role.mcps?.length)
+        loadRoleMcpConfig(getAgentDir(), role.mcps, { codemode: roleActivatesCodemode(role.tools) });
+    const resources = await resolveRolePackageResources(role, ctx);
+    const effectiveRole = { ...role, extensions: resources.extensions };
+    const namedSkills = resolveRoleSkills(pi, effectiveRole);
+    const skills = {
+        ...namedSkills,
+        paths: [...new Set([...namedSkills.paths, ...resources.skills])],
+    };
+    const prepared = prepareRoleLaunchFromSkills(ctx, {
+        role: effectiveRole,
+        route: resolveTaskRoute(ctx, input.modelClass),
+    }, skills);
+    assertNoMissingRoleSkills(effectiveRole, prepared);
+    const args = [
+        ...prepared.args,
+        "--no-prompt-templates",
+        "--no-themes",
+        ...resources.prompts.flatMap((path) => ["--prompt-template", path]),
+        ...resources.themes.flatMap((path) => ["--theme", path]),
+    ];
+    return { ...prepared, args, promptArgIndex: args.length };
+}
+/** Insert the system prompt pair after a caller has prepared its launch argv. */
+export function finalizeRoleLaunch(prepared) {
+    const args = [...prepared.args];
+    args.splice(prepared.promptArgIndex, 0, SYSTEM_PROMPT_FLAG, prepared.systemPrompt);
+    return {
+        env: prepared.env,
+        args,
+        model: prepared.model,
+        thinkingLevel: prepared.thinkingLevel,
+        missingSkills: prepared.missingSkills,
+    };
+}
+export * from "./composition.js";
+export * from "./git-runtime.js";
+export * from "./herdr-runtime.js";
+export { ISOLATED_MODEL_TASK, RoleLaunchRuntime } from "./launch-runtime.js";
+export * from "./runner.js";
+export * from "./schema.js";
+export * from "./store.js";

package/dist/integration-git.d.ts

@@ -0,0 +1,63 @@
+import { type WorktreeInfo } from "./worktree.ts";
+import { type CheckBatchEvidence, type CheckCommand, type IntegrationCandidate, type ReviewEvidence, type WorkspaceIdentity } from "./schema.ts";
+export type StageReceipt = {
+    previous: WorkspaceIdentity;
+    worker: WorkspaceIdentity;
+    tip: WorkspaceIdentity;
+};
+export type GitOutcome<T> = {
+    outcome: "ready";
+    value: T;
+} | {
+    outcome: "blocked" | "conflict" | "drift" | "unknown";
+    failure: string;
+    possibleResources?: string[];
+};
+export declare class IntegrationGit {
+    /** Refresh is allowed only for the exact clean checked-out Main and a strict same-branch descendant. */
+    inspectMainAdvance(root: string, from: WorkspaceIdentity, to: WorkspaceIdentity, signal: AbortSignal): Promise<void>;
+    /** Persist the prepared path/branch/base before Git is allowed to create anything. */
+    allocate(root: string, childId: string, base: WorkspaceIdentity, onPrepared: (info: WorktreeInfo) => Promise<void>, signal: AbortSignal, nameParts?: readonly string[]): Promise<GitOutcome<WorktreeInfo>>;
+    /** Prove each recorded merge before any new merge or final gate. */
+    inspectCombined(root: string, integration: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], signal: AbortSignal): Promise<WorkspaceIdentity>;
+    /** Main's correction is one exact committed child of the checked staged tip. */
+    inspectCorrection(root: string, integration: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], from: WorkspaceIdentity, to: WorkspaceIdentity, signal: AbortSignal): Promise<void>;
+    /** Main orders calls. On conflict leave MERGE_HEAD and the index untouched for manual resolution. */
+    stage(root: string, integration: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], worker: WorktreeInfo, candidate: WorkspaceIdentity, signal: AbortSignal): Promise<GitOutcome<StageReceipt>>;
+    /** After manual conflict resolution: only the exact two-parent merge is a valid receipt. */
+    confirmStage(root: string, integration: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], worker: WorktreeInfo, candidate: WorkspaceIdentity, signal: AbortSignal): Promise<GitOutcome<StageReceipt>>;
+    /** Reconcile an interrupted merge without retrying it or discarding conflict state. */
+    reconcileStage(root: string, integration: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], worker: WorktreeInfo, candidate: WorkspaceIdentity, signal: AbortSignal): Promise<GitOutcome<StageReceipt | "not_started">>;
+    inspectWorker(root: string, worker: WorktreeInfo, candidate: WorkspaceIdentity, signal: AbortSignal): Promise<void>;
+    /** Read-only reconciliation of a lost promotion response; never repeat the merge. */
+    reconcilePromotion(root: string, integration: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], signal: AbortSignal, correction?: {
+        from: WorkspaceIdentity;
+        to: WorkspaceIdentity;
+    }): Promise<GitOutcome<WorkspaceIdentity>>;
+    /** Checks/review must be persisted for this exact combined tip; never move Main via update-ref. */
+    promote(input: {
+        root: string;
+        integration: WorktreeInfo;
+        base: WorkspaceIdentity;
+        stages: readonly StageReceipt[];
+        checks: CheckBatchEvidence;
+        commands: readonly CheckCommand[];
+        /** Staged candidates that may supply reused final results; omitted accepts no reuse. */
+        sources?: readonly IntegrationCandidate[];
+        review?: ReviewEvidence;
+        criterion?: string;
+        correction?: {
+            from: WorkspaceIdentity;
+            to: WorkspaceIdentity;
+        };
+    }, signal: AbortSignal): Promise<GitOutcome<WorkspaceIdentity>>;
+    /** Read-only proof that an owned checkout, its registration, and its branch are all gone. */
+    absent(root: string, info: WorktreeInfo, signal: AbortSignal): Promise<boolean>;
+    /** Explicit release of an unselected clean checkout. The branch deletion is an exact ref compare-and-swap. */
+    release(root: string, info: WorktreeInfo, expected: WorkspaceIdentity, kind: "worktree" | "branch", signal: AbortSignal): Promise<GitOutcome<"removed" | "absent">>;
+    /** Cleanup is deliberately separate per resource; callers persist each proven substep. */
+    cleanup(root: string, integration: WorktreeInfo, info: WorktreeInfo, base: WorkspaceIdentity, stages: readonly StageReceipt[], promoted: WorkspaceIdentity, kind: "worktree" | "branch", signal: AbortSignal, correction?: {
+        from: WorkspaceIdentity;
+        to: WorkspaceIdentity;
+    }): Promise<GitOutcome<"removed" | "absent">>;
+}