@hcflabs/pi-subagent 0.0.0-stage → 27.10.8

package/dist/launch-runtime.js

@@ -0,0 +1,178 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdtemp, open, realpath, rmdir, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, normalize } from "node:path";
+import { resolveConfiguredRoleLaunch } from "./index.js";
+import { registerModelTask } from "@hcflabs/pi-task-models";
+import { isMissing, isWithin } from "./worktree.js";
+const PROMPT_FLAG = "--append-system-prompt";
+const DIRECTORY_MODE = 0o700;
+const PROMPT_MODE = 0o600;
+export const ISOLATED_MODEL_TASK = {
+    id: "pi-subagent/isolatedRoleLaunch",
+    label: "Isolated Role launch",
+    purpose: "Resolve one task-scoped isolated Role launch.",
+    defaultProfile: "balanced",
+};
+async function removeTransientLaunch(directory, promptPath, promptRequired) {
+    const failures = [];
+    try {
+        await unlink(promptPath);
+    }
+    catch (error) {
+        if (promptRequired || !isMissing(error)) {
+            failures.push(new Error(`Could not remove transient Role prompt ${promptPath}.`, { cause: error }));
+        }
+    }
+    try {
+        await rmdir(directory);
+    }
+    catch (error) {
+        failures.push(new Error(`Could not remove transient Role launch directory ${directory}.`, { cause: error }));
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new AggregateError(failures, "Transient Role launch cleanup was incomplete.");
+}
+export async function materializeTransientLaunch(prepared, signal) {
+    signal?.throwIfAborted();
+    const promptBytes = Buffer.from(prepared.prompt, "utf8");
+    const created = await mkdtemp(join(tmpdir(), "pi-subagent-role-"));
+    let directory = normalize(created);
+    let promptPath = join(directory, "system-prompt");
+    let promptCreated = false;
+    let file;
+    try {
+        directory = normalize(await realpath(created));
+        promptPath = join(directory, "system-prompt");
+        await chmod(directory, DIRECTORY_MODE);
+        const directoryInfo = await lstat(directory);
+        if (directoryInfo.isSymbolicLink() || !directoryInfo.isDirectory()
+            || (directoryInfo.mode & 0o7777) !== DIRECTORY_MODE
+            || !isWithin(normalize(await realpath(tmpdir())), directory)) {
+            throw new Error("Transient Role launch directory is not unique canonical mode 0700 OS-temp storage.");
+        }
+        file = await open(promptPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, PROMPT_MODE);
+        promptCreated = true;
+        await file.chmod(PROMPT_MODE);
+        signal?.throwIfAborted();
+        await file.writeFile(promptBytes, { signal });
+        await file.sync();
+        await file.close();
+        file = undefined;
+        const promptInfo = await lstat(promptPath);
+        if (promptInfo.isSymbolicLink() || !promptInfo.isFile()
+            || (promptInfo.mode & 0o7777) !== PROMPT_MODE
+            || normalize(await realpath(promptPath)) !== promptPath) {
+            throw new Error("Transient Role prompt is not a canonical mode 0600 regular file.");
+        }
+        const args = [...prepared.launch.args];
+        args.splice(prepared.promptArgIndex, 0, PROMPT_FLAG, promptPath);
+        const launch = Object.freeze({
+            ...prepared.launch,
+            args: Object.freeze(args),
+        });
+        let cleanup;
+        return Object.freeze({
+            launch,
+            cleanup: async () => await (cleanup ??= removeTransientLaunch(directory, promptPath, true)),
+        });
+    }
+    catch (error) {
+        const failures = [error];
+        if (file) {
+            try {
+                await file.close();
+            }
+            catch (closeError) {
+                failures.push(closeError);
+            }
+        }
+        try {
+            await removeTransientLaunch(directory, promptPath, promptCreated);
+        }
+        catch (cleanupError) {
+            failures.push(cleanupError);
+        }
+        if (failures.length > 1) {
+            throw new AggregateError(failures, `Transient Role prompt materialization for ${prepared.launch.role} failed and cleanup was incomplete.`);
+        }
+        throw error;
+    }
+}
+export class RoleLaunchRuntime {
+    options;
+    constructor(options) {
+        this.options = options;
+        registerModelTask(options.pi, ISOLATED_MODEL_TASK);
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    randomToken() {
+        return this.options.randomToken?.() ?? randomBytes(12).toString("hex");
+    }
+    async prepareLaunch(role, modelClass, context) {
+        context.signal?.throwIfAborted();
+        const prepared = await resolveConfiguredRoleLaunch(this.options.pi, this.options.context(), { role, modelClass });
+        return Object.freeze({
+            launch: Object.freeze({
+                role: prepared.role,
+                modelClass,
+                model: `${prepared.model.provider}/${prepared.model.id}`,
+                thinkingLevel: prepared.thinkingLevel,
+                args: Object.freeze([...prepared.args]),
+                env: Object.freeze({ ...prepared.env }),
+                tools: Object.freeze([...prepared.tools]),
+            }),
+            prompt: prepared.systemPrompt,
+            promptArgIndex: prepared.promptArgIndex,
+        });
+    }
+    async preflight(input, context) {
+        context.signal?.throwIfAborted();
+        const resolvedRoot = await this.options.resolveRoot(input.cwd, context);
+        if (typeof resolvedRoot !== "string" || !isAbsolute(resolvedRoot) || resolvedRoot.includes("\0")) {
+            throw new Error("Pi Subagent root resolver must return an absolute canonical path.");
+        }
+        const root = await realpath(resolvedRoot);
+        if (root !== resolvedRoot)
+            throw new Error("Pi Subagent root resolver returned a non-canonical path.");
+        const rootInfo = await lstat(root);
+        if (!rootInfo.isDirectory())
+            throw new Error("Pi Subagent root must be an existing local directory.");
+        context.signal?.throwIfAborted();
+        if (!input.dryRun && input.request.tasks.some((task) => task.kind === "changeset")) {
+            await this.options.preflightHost?.({ request: input.request, cwd: input.cwd, root }, context);
+        }
+        const main = await this.options.inspectMainBase({ root }, context);
+        const required = new Map();
+        const addRequired = (role, modelClass) => {
+            const modelClasses = required.get(role) ?? new Set();
+            modelClasses.add(modelClass);
+            required.set(role, modelClasses);
+        };
+        for (const task of input.request.tasks) {
+            addRequired(task.role, task.modelClass);
+            if (task.kind === "changeset" && task.judgment)
+                addRequired(task.judgment.role, task.judgment.modelClass);
+        }
+        if (input.request.finalJudgment) {
+            addRequired(input.request.finalJudgment.role, input.request.finalJudgment.modelClass);
+        }
+        const routes = [];
+        for (const [role, modelClasses] of required) {
+            for (const modelClass of modelClasses) {
+                const { launch } = await this.prepareLaunch(role, modelClass, context);
+                routes.push({ role, modelClass, model: launch.model, thinkingLevel: launch.thinkingLevel });
+            }
+        }
+        return { root, main, routes };
+    }
+    async acquireLaunch(role, modelClass, context) {
+        const prepared = await this.prepareLaunch(role, modelClass, context);
+        return await materializeTransientLaunch(prepared, context.signal);
+    }
+}

package/dist/mcp-role.d.ts

@@ -0,0 +1,12 @@
+import type { LoadedMcpConfig } from "@earendil-works/pi-coding-agent";
+export declare function parseRoleMcpAllowlist(value: unknown): string[];
+/**
+ * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
+ * shape; the project `.pi/mcp.json` is ignored. A child that activates `codemode` keeps each
+ * server's configured exposure, so scripts reach `codemode` and `deferred` tools. Any other child
+ * cannot reach undeclared tools, so every selected server is forced to direct exposure. Codemode is
+ * never activated by MCP configuration: the Role tool policy owns the active set.
+ */
+export declare function loadRoleMcpConfig(agentDir: string, allowlist: readonly string[], options?: {
+    codemode: boolean;
+}): LoadedMcpConfig;

package/dist/mcp-role.js

@@ -0,0 +1,152 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+export function parseRoleMcpAllowlist(value) {
+    if (typeof value !== "string")
+        throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
+    }
+    if (!Array.isArray(parsed)
+        || parsed.some((name) => typeof name !== "string" || !name.trim() || name.includes("\0"))) {
+        throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
+    }
+    const names = parsed.map((name) => name.trim());
+    if (new Set(names).size !== names.length)
+        throw new Error("The Role MCP policy flag contains duplicate MCP server names.");
+    return names;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const isString = (value) => typeof value === "string";
+const isStringRecord = (value) => isRecord(value) && Object.values(value).every(isString);
+const parseUrl = (value) => (typeof value === "string" && URL.canParse(value) ? new URL(value) : undefined);
+// Pi's native MCP rules (core/mcp-servers.ts); `validateMcpServerConfig` is not exported, so they are mirrored here.
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+const isHttpsOrLoopback = (url) => url !== undefined && (url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname)));
+/** Tool namespace `mcp__<server>` replaces `-` with `_`, so names differing only there collide. */
+const mcpNamespace = (name) => name.replace(/-/g, "_");
+// Pi's exposure names and the alias it still accepts (core/mcp-servers.ts); the native loader is bypassed, so resolve it here.
+const MCP_EXPOSURES = ["codemode", "deferred", "direct", "hidden"];
+const MCP_EXPOSURE_ALIASES = { "codemode-deferred": "codemode" };
+const resolveExposure = (value) => MCP_EXPOSURE_ALIASES[value] ?? value;
+const isExposure = (value) => typeof value === "string" && MCP_EXPOSURES.includes(resolveExposure(value));
+/** Documented `mcpServers` fields (Pi's docs/mcp.md) and their shapes, by transport; dotted keys are nested. */
+const COMMON_CHECKS = {
+    enabled: [(value) => typeof value === "boolean", "a boolean"],
+    timeout: [(value) => typeof value === "number" && Number.isFinite(value) && value > 0, "a positive number"],
+    description: [isString, "a string"],
+};
+const STDIO_CHECKS = {
+    args: [(value) => Array.isArray(value) && value.every(isString), "an array of strings"],
+    env: [isStringRecord, "an object of strings"],
+    cwd: [isString, "a string"],
+};
+const HTTP_CHECKS = {
+    url: [(value) => /^https?:$/.test(parseUrl(value)?.protocol ?? ""), "an http or https URL"],
+    headers: [isStringRecord, "an object of strings"],
+    oauth: [isRecord, "an object"],
+    "oauth.clientId": [isString, "a string"],
+    "oauth.clientSecret": [isString, "a string"],
+    "oauth.callbackPort": [(value) => Number.isInteger(value) && value >= 1 && value <= 65535, "a port number"],
+    "oauth.callbackUrl": [(value, server) => {
+            const url = parseUrl(value);
+            const port = server.oauth.callbackPort;
+            return url !== undefined && url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname) && url.search === "" && url.hash === ""
+                && (url.port === "" || port === undefined || Number(url.port) === port);
+        }, "an http URL on localhost, 127.0.0.1, or [::1] without query or fragment, on the \"oauth.callbackPort\" port"],
+    "oauth.scope": [isString, "a string"],
+    "oauth.clientName": [(value) => typeof value === "string" && value.trim() !== "", "a non-empty string"],
+    "oauth.clientRegistration": [(value) => value === "dcr" || value === "cimd", '"dcr" or "cimd"'],
+    "oauth.authServerMetadataUrl": [(value) => isHttpsOrLoopback(parseUrl(value)), "an https URL, or http on localhost, 127.0.0.1, or [::1]"],
+    auth: [(value) => isRecord(value) && typeof value.provider === "string" && value.provider !== "", "an object with a non-empty \"provider\" string"],
+};
+const EXPOSURE_CHECKS = {
+    exposure: [isExposure, `one of ${MCP_EXPOSURES.map((exposure) => `"${exposure}"`).join(", ")}`],
+    toolExposure: [(value) => isRecord(value) && Object.values(value).every(isExposure), "an object mapping tool names to exposures"],
+};
+/** Validate one selected server against Pi's documented `mcpServers` rules; the native loader is bypassed by `loadConfig`. */
+function validateRoleMcpServer(path, name, value, codemode) {
+    const fail = (message) => { throw new Error(`${path}: MCP server "${name}" ${message}`); };
+    if (!SERVER_NAME.test(name))
+        fail("has an invalid name (use letters, digits, \"_\" and \"-\").");
+    if (!isRecord(value))
+        fail("must be an object.");
+    if (value.enabled === false)
+        throw new Error(`${path}: Role MCP server "${name}" is disabled.`);
+    const stdio = typeof value.command === "string" && value.command.trim() !== "" && (value.type === undefined || value.type === "stdio");
+    const http = typeof value.url === "string" && value.url.trim() !== "" && (value.type === undefined || value.type === "http" || value.type === "streamable-http");
+    if (stdio === http)
+        fail("needs either a \"command\" (stdio) or a \"url\" (http or streamable-http).");
+    for (const [field, [valid, shape]] of Object.entries({ ...COMMON_CHECKS, ...(stdio ? STDIO_CHECKS : HTTP_CHECKS), ...(codemode ? EXPOSURE_CHECKS : {}) })) {
+        const fieldValue = field.split(".").reduce((parent, key) => (isRecord(parent) ? parent[key] : undefined), value);
+        if (fieldValue !== undefined && !valid(fieldValue, value))
+            fail(`field "${field}" must be ${shape}.`);
+    }
+    if (http && isRecord(value.oauth) && value.oauth.clientRegistration === "cimd") {
+        if (value.oauth.clientId !== undefined || value.oauth.clientName !== undefined) {
+            fail('field "oauth.clientRegistration" "cimd" cannot be combined with "oauth.clientId" or "oauth.clientName".');
+        }
+        const callback = parseUrl(value.oauth.callbackUrl);
+        if (callback && (callback.hostname === "[::1]" || callback.pathname !== "/callback")) {
+            fail('field "oauth.clientRegistration" "cimd" requires "oauth.callbackUrl" on localhost or 127.0.0.1 with path /callback.');
+        }
+    }
+    // The native transport sends the provider's token to `url`, so Pi only allows it over https or loopback.
+    if (value.auth !== undefined && !isHttpsOrLoopback(parseUrl(value.url))) {
+        fail("field \"auth\" requires \"url\" to use https, or http on localhost, 127.0.0.1, or [::1].");
+    }
+    if (codemode) {
+        const { exposure, toolExposure } = value;
+        return {
+            ...value,
+            ...(typeof exposure === "string" ? { exposure: resolveExposure(exposure) } : {}),
+            ...(isRecord(toolExposure) ? { toolExposure: Object.fromEntries(Object.entries(toolExposure).map(([tool, entry]) => [tool, resolveExposure(entry)])) } : {}),
+        };
+    }
+    const { toolExposure: _toolExposure, ...config } = value;
+    return { ...config, exposure: "direct" };
+}
+/**
+ * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
+ * shape; the project `.pi/mcp.json` is ignored. A child that activates `codemode` keeps each
+ * server's configured exposure, so scripts reach `codemode` and `deferred` tools. Any other child
+ * cannot reach undeclared tools, so every selected server is forced to direct exposure. Codemode is
+ * never activated by MCP configuration: the Role tool policy owns the active set.
+ */
+export function loadRoleMcpConfig(agentDir, allowlist, options = { codemode: false }) {
+    // A Role without mcps must not depend on mcp.json being readable.
+    if (!allowlist.length)
+        return { servers: [], autoEnableCodemode: false, errors: [] };
+    const path = join(agentDir, "mcp.json");
+    let parsed = {};
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+            throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    if (!isRecord(parsed) || (parsed.mcpServers !== undefined && !isRecord(parsed.mcpServers))) {
+        throw new Error(`${path}: expected an object with an "mcpServers" object.`);
+    }
+    const configured = parsed.mcpServers ?? {};
+    const missing = allowlist.filter((name) => !Object.hasOwn(configured, name));
+    if (missing.length)
+        throw new Error(`Role MCP servers are not configured: ${missing.join(", ")}.`);
+    const namespaces = new Map();
+    const servers = allowlist.map((name) => {
+        const clash = namespaces.get(mcpNamespace(name));
+        if (clash)
+            throw new Error(`${path}: Role MCP server "${name}" conflicts with "${clash}": names that differ only in "-" and "_" share one tool namespace.`);
+        namespaces.set(mcpNamespace(name), name);
+        return { name, config: validateRoleMcpServer(path, name, configured[name], options.codemode), source: path, scope: "global" };
+    });
+    return { servers, autoEnableCodemode: false, errors: [] };
+}

package/dist/process-lease.d.ts

@@ -0,0 +1,5 @@
+import type { HerdrExecResult } from "@hcflabs/pi-herdr";
+export declare const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
+export declare function assertPrivateLease(path: string, allowMissing: boolean): Promise<boolean>;
+/** Shared exact process-lease evidence for direct and isolated workers. */
+export declare function scanProcessLease(path: string, execute: (args: string[]) => Promise<HerdrExecResult>, pid?: number, allowMissing?: boolean): Promise<number[]>;

package/dist/process-lease.js

@@ -0,0 +1,43 @@
+import { lstat } from "node:fs/promises";
+export const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
+export async function assertPrivateLease(path, allowMissing) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return false;
+        throw new Error(`Exact process lease cannot be inspected: ${path}`, { cause: error });
+    }
+    const uid = process.getuid?.();
+    if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o777) !== 0o600 || (uid !== undefined && info.uid !== uid)) {
+        throw new Error("Exact process lease must be a current-user regular non-symlink mode-0600 file.");
+    }
+    return true;
+}
+/** Shared exact process-lease evidence for direct and isolated workers. */
+export async function scanProcessLease(path, execute, pid, allowMissing = false) {
+    if (!await assertPrivateLease(path, allowMissing))
+        return [];
+    // -w: host-wide warnings (for example an unreachable network mount) are not lease evidence; real errors still reach stderr.
+    const args = ["-w", "-nP", "-a", ...(pid === undefined ? [] : ["-p", String(pid)]), "-F", "p", "--", path];
+    const result = await execute(args);
+    if (result.killed || ![0, 1].includes(result.code) || (result.code === 1 && (result.stdout.trim() || result.stderr.trim()))) {
+        throw new Error("Exact process lease lsof scan failed or was ambiguous.");
+    }
+    if (result.code === 1)
+        return [];
+    if (result.stderr.trim())
+        throw new Error("Exact process lease lsof scan returned unexpected diagnostics.");
+    // lsof always selects the file descriptor field, so `-F p` also emits `f<fd>` lines.
+    const lines = result.stdout.trim().split(/\r?\n/).filter((line) => line && !/^f\w+$/.test(line));
+    if (!lines.length || lines.some((line) => !/^p[1-9]\d*$/.test(line))) {
+        throw new Error("Exact process lease lsof scan returned malformed PID fields.");
+    }
+    const holders = [...new Set(lines.map((line) => Number(line.slice(1))))];
+    if (holders.some((holder) => !Number.isSafeInteger(holder) || holder <= 0) || (pid !== undefined && holders.some((holder) => holder !== pid))) {
+        throw new Error("Exact process lease lsof scan returned an unexpected PID.");
+    }
+    return holders;
+}

package/dist/process.d.ts

@@ -0,0 +1,9 @@
+type ProcessOptions = {
+    cwd: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    stdin?: string;
+};
+/** Infrastructure errors reject; only ordinary command exits return a result. */
+export declare const runProcess: (command: string, args: string[], options: ProcessOptions) => Promise<import("@hcflabs/pi-process").ExecResult>;
+export {};

package/dist/process.js

@@ -0,0 +1,11 @@
+import { spawnBounded } from "@hcflabs/pi-process";
+const OUTPUT_LIMIT_BYTES = 1024 * 1024;
+/** Infrastructure errors reject; only ordinary command exits return a result. */
+export const runProcess = async (command, args, options) => await spawnBounded(command, args, {
+    cwd: options.cwd,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs ?? null,
+    ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+    stdoutLimitBytes: OUTPUT_LIMIT_BYTES,
+    stderrLimitBytes: OUTPUT_LIMIT_BYTES,
+});

package/dist/prune.d.ts

@@ -0,0 +1,78 @@
+import { type GitRunner } from "./git-process.ts";
+/** Blockers that a separately confirmed force removal of an unowned item may override; every other kind is hard. */
+export declare const FORCEABLE_PRUNE_BLOCKERS: readonly ["unmerged", "changes", "operation", "submodules"];
+export type PruneBlockerKind = typeof FORCEABLE_PRUNE_BLOCKERS[number] | "owner" | "lease" | "hard";
+export interface PruneBlocker {
+    kind: PruneBlockerKind;
+    text: string;
+}
+/** Saved identity of a readable request that owns a resource name. */
+export interface PruneRequest {
+    id: string;
+    name: string;
+    status: string;
+    directory: string;
+    root: string;
+    orphaned: boolean;
+}
+/** One reviewed pi-subagent branch, with its registered checkout when one exists. */
+export interface PruneItem {
+    branch: string;
+    tip: string;
+    path?: string;
+    prunable: boolean;
+    /** Why the item is prunable, or every exact blocker. */
+    reason: string;
+    blockers: readonly PruneBlocker[];
+    /** The only, readable request that owns the item. */
+    owner?: PruneRequest;
+    /** How a blocked item can still go after separate confirmation: discard of its whole owning request, or
+     * force removal when every blocker is forceable. Absent for prunable and hard-blocked items. */
+    override?: "discard" | "force";
+    /** Ignored entries as Git collapses them; removing the checkout deletes them. */
+    ignored: readonly string[];
+}
+export interface PruneOwnership {
+    /** Every request or state that may still own an exact resource name; unreadable state has no request. */
+    owners(name: string): readonly {
+        label: string;
+        request?: PruneRequest;
+    }[];
+    /** The live productive lease that blocks pruning, if any. */
+    lease?: string;
+}
+export interface PruneGuards {
+    /** Ownership and lease evidence across the repository's existing checkouts, primary first. */
+    ownership(checkouts: readonly string[]): Promise<PruneOwnership>;
+    /** Every Herdr pane; rejects when Herdr cannot be inspected. */
+    panes(): Promise<readonly {
+        paneId: string;
+        cwds: readonly string[];
+    }[]>;
+    /** The confirming session still owns the command; checked immediately before each removal step. */
+    current?(): boolean;
+}
+export type PruneRemoval = {
+    outcome: "removed" | "skipped" | "failed";
+    item: PruneItem;
+    reason: string;
+};
+export declare function requireGit(run: GitRunner, args: string[], cwd: string): Promise<string>;
+export declare const within: (directory: string, path: string) => boolean;
+/** Every pane in every Herdr workspace with its shell and foreground working directories. */
+export declare function listHerdrPanes(cwd: string): Promise<{
+    paneId: string;
+    cwds: string[];
+}[]>;
+/** Read-only review of every pi-subagent worker or integration branch and its checkout. */
+export declare function inspectPruneCandidates(root: string, mainCwd: string, guards: PruneGuards, run?: GitRunner): Promise<PruneItem[]>;
+/**
+ * Re-verify each reviewed prunable item immediately before removing its checkout, then delete its
+ * branch only at the reviewed tip. Ignored entries are deleted only when `allowIgnored` and all of
+ * them were in the review. With `force`, a reviewed forceable item is removed with `--force` while
+ * every fresh blocker is forceable and of a reviewed kind. Returns the repository checkouts that still exist.
+ */
+export declare function removePruneCandidates(root: string, mainCwd: string, reviewed: readonly PruneItem[], allowIgnored: boolean, force: boolean, guards: PruneGuards, run?: GitRunner): Promise<{
+    removals: PruneRemoval[];
+    checkouts: string[];
+}>;