pi-extensible-workflows 3.0.0 → 3.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 Turn multi-agent tasks into deterministic jobs that fan out in parallel, pause for approval, and resume without rerunning completed work.
 
-[Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html)
+[Documentation](https://vekexasia.github.io/pi-extensible-workflows/) | [Developer guide](https://vekexasia.github.io/pi-extensible-workflows/developers.html) | [Agent guide](https://vekexasia.github.io/pi-extensible-workflows/agents.html) | [Extension authoring](https://vekexasia.github.io/pi-extensible-workflows/extensions.html) | [Video overview](https://youtu.be/qAiivspEHmU)
 
 Requires Node.js 22.19 or newer. This is a trusted Pi extension with the same filesystem and process access as Pi.
 
@@ -20,35 +20,32 @@ For source installs and local development, see the [installation guide](https://
 
 ## Capabilities
 
-The main Pi agent acts as the orchestrator: it writes workflow scripts on the fly for each task. Pi extensions can add reusable functions and variables to those scripts; every registered function is also directly runnable as a top-level workflow.
-
-Inline workflow launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
-
-A workflow can fan out across specialized agents, combine their results, and resume without rerunning completed work.
+The default path is a named inline workflow: write a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns. Inline launches require a non-empty `name`; registered function launches reject `name` and use their registered function name as the run name. Runs are backgrounded by default; set `foreground: true` when the final value must be returned in the same tool call.
 
 ```js
 const reviews = await parallel("review", {
   correctness: () => agent("Review the current changes for correctness issues."),
-  security: () => agent("Review the current changes for security risks.", {
-    role: "security-specialist",
-  }),
+  security: () => agent("Review the current changes for security risks."),
   tests: () => agent("Review the current changes for missing test coverage."),
 });
 
-const summary = await agent(
-  prompt("Deduplicate and prioritize these findings:\n\n{reviews}", { reviews }),
+return await agent(
+  prompt("Summarize and prioritize these findings:\n\n{reviews}", { reviews }),
 );
-
-return summary;
 ```
 
+**Advanced capabilities:** Use registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` when the task requires them. They remain available without complicating the basic inline path. Workflow worktree scopes always use the explicit `withWorktree(name, callback)` form.
+
+The main Pi agent writes these scripts on the fly for each task; extensions can add reusable functions and variables, and completed workflows can resume without rerunning completed work.
+
 Learn more about roles, workflow contracts, and extension APIs in the documentation:
 
 - [Workflow tool and invocation API](https://vekexasia.github.io/pi-extensible-workflows/developers.html#tool-api)
 - [Global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings)
 - [Aggregate run budgets](https://vekexasia.github.io/pi-extensible-workflows/developers.html#budgets)
 - [Workflow DSL and worktrees](https://vekexasia.github.io/pi-extensible-workflows/developers.html#dsl)
-- [Reusable extension primitives](https://vekexasia.github.io/pi-extensible-workflows/developers.html#extensions)
+- [Extension authoring guide](https://vekexasia.github.io/pi-extensible-workflows/extensions.html)
+- [Copy-paste extension template](https://github.com/vekexasia/pi-extensible-workflows/tree/main/examples/workflow-extension-template)
 - [Run artifacts and lifecycle events](https://vekexasia.github.io/pi-extensible-workflows/developers.html#lifecycle)
 - [Run inspection and recovery](https://vekexasia.github.io/pi-extensible-workflows/developers.html#operations)
 - [Agent patterns and model selection](https://vekexasia.github.io/pi-extensible-workflows/agents.html#patterns)
@@ -56,20 +53,21 @@ Learn more about roles, workflow contracts, and extension APIs in the documentat
 
 ## Configuration
 
-Global workflow settings live at `~/.pi/agent/pi-extensible-workflows/settings.json` by default and configure concurrency, model aliases, and workflow-agent skill or extension exclusions. Trusted projects can add resource exclusions at `<project>/.pi/pi-extensible-workflows/settings.json`; they cannot override global aliases or concurrency. See [global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings) for the schema and merge rules.
+Global workflow settings live at `~/.pi/agent/pi-extensible-workflows/settings.json` by default. Trusted projects can add partial overrides at `<project>/.pi/pi-extensible-workflows/settings.json`; precedence is defaults < global < trusted project < per-run options. Project collections replace global collections, so `{}` and empty arrays clear inherited aliases or resource exclusions. Untrusted project settings are ignored. See [global and project settings](https://vekexasia.github.io/pi-extensible-workflows/developers.html#settings) for the schema, trust gate, source reporting, and merge rules.
 
 ## CLI
 
 ```sh
 npx pi-extensible-workflows doctor
+npx pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]
 npx pi-extensible-workflows inspect [session-id]
 npx pi-extensible-workflows transcript <session-file>
 npx pi-extensible-workflows run <workflow-name> [workflow arguments]
 npx pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]
 ```
 
-`doctor` validates the installation and active Pi resources. `inspect` opens a read-only terminal view of persisted workflow runs. `transcript` renders a session transcript to stdout. `run` derives flat CLI arguments and help from a registered function's input schema. Use `--input '<json>'` for nested or otherwise complex inputs. It executes in the current working directory, writes the final JSON result to stdout, and writes progress and errors to stderr. `export` creates an executable POSIX launcher in `~/.local/bin` by default.
-`run` and `export` accept the trust overrides `--approve` and `--no-approve`; the generated launcher forwards its arguments to `run`. `--` ends launcher option parsing, and later tokens are passed to workflow input instead of being interpreted as launcher options.
+`doctor` validates the installation and active Pi resources and remains read-only. `doctor cleanup` is an explicit, dry-run-first maintenance command: it previews terminal workflow runs older than 90 days across the current project's stored sessions and deletes them only with `--yes`; use `--older-than-days` to change the positive age threshold. It protects active, corrupt, leased, and dependency-linked runs. `inspect` opens a read-only terminal view of persisted workflow runs. `transcript` renders a session transcript to stdout. `run` derives flat CLI arguments and help from a registered function's input schema. Use `--input '<json>'` for nested or otherwise complex inputs. It executes in the current working directory, writes the final JSON result to stdout, and writes progress and errors to stderr. `export` creates an executable POSIX launcher in `~/.local/bin` by default.
+`run` and `export` accept the trust overrides `--approve` and `--no-approve`; the generated launcher forwards its arguments to `run`. `--` ends launcher option parsing, and later tokens are passed to workflow input instead of being interpreted as launcher options. Headless `run` and generated `export` launchers cannot execute workflows containing checkpoints; use the Pi workflow tool/UI path for checkpointed workflows.
 Launch snapshots use identity version 5. Cold resume rejects older snapshots, including v4 snapshots created with the previous worktree or registered-function naming contracts, with `RESUME_INCOMPATIBLE`; relaunch the workflow instead.
 
 ## Development

package/dist/src/agent-execution.d.ts

@@ -1,22 +1,8 @@
-import { type AgentSessionEvent, type InlineExtension, type SessionStats, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-type AgentMessage = {
-    role: string;
-    content?: unknown;
-    stopReason?: string;
-    errorMessage?: string;
-    usage?: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-        cost: {
-            total: number;
-        };
-    };
-};
-import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, WorkflowRunContext } from "./types.js";
+import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput, WorkflowRunContext } from "./types.js";
 import type { RunStore } from "./persistence.js";
+export type { AgentSetup, AgentSetupContext, AgentSetupHook, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput } from "./types.js";
 export interface AgentBudgetHooks {
     beforeAttempt(): void;
     beforeTurn(): void;
@@ -121,68 +107,6 @@ export interface AgentExecutionResult {
     attempts: readonly AgentAttempt[];
     cwd: string;
 }
-export interface AgentSetup {
-    prompt: string;
-    options: Record<string, JsonValue>;
-    sessionInput: SessionInput;
-    createSession: SessionFactory;
-}
-export interface AgentSetupContext {
-    readonly run: Readonly<WorkflowRunContext>;
-    readonly identity: Readonly<AgentIdentity>;
-    readonly attempt: number;
-    readonly signal: AbortSignal;
-}
-export interface AgentSetupHook {
-    priority?: number;
-    setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void>;
-}
-export interface RegisteredAgentSetupHook {
-    name: string;
-    priority: number;
-    setup: AgentSetupHook["setup"];
-}
-type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
-export interface NativeSession {
-    readonly sessionId: string;
-    readonly sessionFile: string | undefined;
-    readonly messages: readonly AgentMessage[];
-    getSessionStats(): NativeSessionStats;
-    readonly systemPrompt?: string;
-    readonly model?: {
-        provider: string;
-        model?: string;
-        id?: string;
-    };
-    readonly agent?: {
-        state: {
-            tools: readonly {
-                name: string;
-            }[];
-        };
-    };
-    getLeafId?: () => string | null;
-    getToolDefinitions?: () => unknown;
-    subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
-    prompt(text: string): Promise<void>;
-    steer?(text: string): Promise<void>;
-    abort?(): Promise<void>;
-    dispose(): void;
-}
-export interface SessionInput {
-    cwd: string;
-    model: ModelSpec;
-    tools: string[];
-    sessionLabel: string;
-    agentDir?: string;
-    customTools?: ToolDefinition[];
-    resultTool?: ToolDefinition;
-    systemPromptAppend?: string;
-    extensionFactories?: InlineExtension[];
-    resourcePolicy?: AgentResourcePolicy;
-    options?: Record<string, JsonValue>;
-}
-export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 export declare function createNativeAgentSession(input: SessionInput): Promise<NativeSession>;
 export declare class WorkflowAgentExecutor {
     private readonly root;
@@ -265,6 +189,7 @@ export declare class FairAgentScheduler {
     private readonly writeOwnership?;
     constructor(runner: ScheduledAgentRunner, sessionLimit?: number, writeOwnership?: OwnershipWriter | undefined);
     addRun(runId: string, limit?: number, beforeLaunch?: () => void): void;
+    updateRunLimit(runId: string, limit: number): void;
     spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): {
         id: string;
         result: Promise<ScheduledAgentResult>;
@@ -282,4 +207,3 @@ export declare class FairAgentScheduler {
     restoreRun(runId: string, limit: number, ownership: readonly OwnershipRecord[], beforeLaunch?: () => void): void;
     flush(): Promise<void>;
 }
-export {};

package/dist/src/agent-execution.js

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
 import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
-import { jsonObject, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference } from "./utils.js";
+import { jsonObject, disabledResources, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference, unmatchedResourcePatterns } from "./utils.js";
 import { WorkflowError } from "./types.js";
 function parseModel(value, fallback, thinking, aliases = {}, knownModels, settingsPath) {
     if (!value)
@@ -69,14 +69,17 @@ export async function createNativeAgentSession(input) {
         settingsManager.setProjectTrusted(policy.projectTrusted);
         const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
         const resolved = await packageManager.resolve();
-        const disabledExtensions = new Set(policy.effective.extensions);
-        const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)).filter((path) => !disabledExtensions.has(canonicalSourcePath(path))))];
+        const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)))];
+        const excludedExtensions = new Set(disabledResources(policy.effective.extensions, discoveredExtensions));
+        const extensionPaths = discoveredExtensions.filter((path) => !excludedExtensions.has(path));
+        Object.assign(policy, { excludedExtensions: [...excludedExtensions], unmatchedExtensions: unmatchedResourcePatterns(policy.effective.extensions, discoveredExtensions) });
         const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
         const updateSkillMatches = (skills) => {
-            const names = new Set(skills.map(({ name }) => name));
-            Object.assign(policy, { unmatchedSkills: policy.effective.skills.filter((name) => !names.has(name)) });
+            const names = [...new Set(skills.map(({ name }) => name))];
+            const excludedSkills = disabledResources(policy.effective.skills, names);
+            Object.assign(policy, { excludedSkills, unmatchedSkills: unmatchedResourcePatterns(policy.effective.skills, names) });
+            return new Set(excludedSkills);
         };
-        const disabledSkills = new Set(policy.effective.skills);
         resourceLoader = new DefaultResourceLoader({
             cwd: input.cwd,
             agentDir,
@@ -87,14 +90,12 @@ export async function createNativeAgentSession(input) {
             additionalSkillPaths: skillPaths,
             ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
             skillsOverride: (base) => {
-                updateSkillMatches(base.skills);
+                const disabledSkills = updateSkillMatches(base.skills);
                 return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
             },
             ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
         });
         await resourceLoader.reload();
-        const discoveredExtensions = new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)));
-        Object.assign(policy, { unmatchedExtensions: policy.effective.extensions.filter((path) => !discoveredExtensions.has(canonicalSourcePath(path))) });
     }
     else if (input.systemPromptAppend || input.extensionFactories?.length) {
         resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
@@ -133,7 +134,7 @@ function fallbackSetupContext(root, options, signal) {
     return { run, identity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) };
 }
 function resourcePolicySummary(policy) {
-    return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
+    return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], excludedSkills: [...(policy.excludedSkills ?? [])], excludedExtensions: [...(policy.excludedExtensions ?? [])], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
 }
 async function prepareAgentSetup(root, createSession, task, options, resolved, cwd, attempt, signal, customTools, resultTool) {
     const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
@@ -520,6 +521,15 @@ export class FairAgentScheduler {
         this.#runs.set(runId, { limit, ...(beforeLaunch ? { beforeLaunch } : {}), logical: 0, active: 0, queue: [] });
         this.#runOrder.push(runId);
     }
+    updateRunLimit(runId, limit) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
+        if (!Number.isInteger(limit) || limit < 1 || limit > this.sessionLimit)
+            throw new WorkflowError("INVALID_SETTINGS", "Invalid run concurrency");
+        run.limit = limit;
+        this.#dispatch();
+    }
     spawn(runId, prompt, options, parentId) {
         const run = this.#runs.get(runId);
         if (!run)

package/dist/src/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type DoctorOptions } from "./doctor.js";
+import { type DoctorCleanupOptions } from "./doctor-cleanup.js";
 import { type JsonSchema, type JsonValue } from "./index.js";
 import type { WorkflowCatalogFunction } from "./index.js";
 export interface CliOptions extends DoctorOptions {
@@ -12,4 +13,5 @@ export interface CliOptions extends DoctorOptions {
 }
 export declare function formatWorkflowCliHelp(fn: WorkflowCatalogFunction, command?: string): string;
 export declare function parseWorkflowCliArgs(schema: JsonSchema, rawArgs: readonly string[]): Record<string, JsonValue>;
+export declare function parseDoctorCleanupArgs(rawArgs: readonly string[]): Required<Pick<DoctorCleanupOptions, "olderThanDays" | "yes">>;
 export declare function runCli(args: readonly string[], options?: CliOptions, write?: (text: string) => void): Promise<number>;

package/dist/src/cli.js

@@ -7,7 +7,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
-import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog } from "./index.js";
+import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";
+import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "./index.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function has(value, key) { return Object.prototype.hasOwnProperty.call(value, key); }
@@ -193,6 +194,34 @@ function launcherHelpLines() {
 }
 function workflowUsage() { return [`Usage: pi-extensible-workflows run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
 function exportUsage() { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+export function parseDoctorCleanupArgs(rawArgs) {
+    let olderThanDays = 90;
+    let yes = false;
+    let seenDays = false;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = rawArgs[index];
+        if (token === "--yes") {
+            yes = true;
+            continue;
+        }
+        const inline = token.startsWith("--older-than-days=") ? token.slice("--older-than-days=".length) : undefined;
+        if (token === "--older-than-days" || inline !== undefined) {
+            if (seenDays)
+                throw new Error("--older-than-days may only be provided once");
+            const raw = inline ?? rawArgs[++index];
+            if (raw === undefined || !/^[1-9]\d*$/.test(raw))
+                throw new Error("older-than-days must be a positive integer");
+            const parsed = Number(raw);
+            if (!Number.isSafeInteger(parsed) || parsed < 1)
+                throw new Error("older-than-days must be a positive integer");
+            olderThanDays = parsed;
+            seenDays = true;
+            continue;
+        }
+        throw new Error(`Unknown cleanup option: ${token}`);
+    }
+    return { olderThanDays, yes };
+}
 function stripTrustOptions(rawArgs) {
     const args = [];
     let trustOverride;
@@ -278,7 +307,7 @@ async function createWorkflowRuntime(options, shutdownHandlers = []) {
     const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow");
     if (!workflowTool)
         throw new Error("The workflow runtime could not be initialized");
-    return { catalog: workflowCatalog(), services, workflowTool, shutdownHandlers };
+    return { catalog: workflowCatalog({ cwd, projectTrusted: settingsManager.isProjectTrusted(), globalSettingsPath: workflowSettingsPath(agentDir) }), services, workflowTool, shutdownHandlers };
 }
 function availableModelInfo(services, available = false) {
     const models = available ? services.modelRuntime.getAvailableSnapshot() : services.modelRuntime.getModels();
@@ -512,6 +541,23 @@ export async function runCli(args, options = {}, write = (text) => { process.std
         write(formatDoctorReport(report));
         return doctorExitCode(report);
     }
+    if (args[0] === "doctor" && args[1] === "cleanup") {
+        if (args.slice(2).some((arg) => arg === "--help" || arg === "-h")) {
+            write("Usage: pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]\n");
+            return 0;
+        }
+        try {
+            const parsed = parseDoctorCleanupArgs(args.slice(2));
+            const cleanupOptions = { ...parsed, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}) };
+            const report = await doctorCleanup(cleanupOptions);
+            write(formatDoctorCleanupReport(report));
+            return doctorCleanupExitCode(report);
+        }
+        catch (error) {
+            stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
     if (args[0] === "inspect" && args.length <= 2) {
         try {
             await (options.inspect ?? runSessionInspector)(args[1]);

package/dist/src/doctor-cleanup.d.ts

@@ -0,0 +1,41 @@
+export interface DoctorCleanupOptions {
+    cwd?: string;
+    home?: string;
+    olderThanDays?: number;
+    yes?: boolean;
+    now?: number;
+}
+export interface CleanupRunResult {
+    sessionId: string;
+    runId: string;
+    action: "candidate" | "skipped" | "deleted" | "failed";
+    state: string;
+    stateMtimeMs: number;
+    path: string;
+    reason?: string;
+}
+export interface CleanupFailure {
+    sessionId: string;
+    runId?: string;
+    message: string;
+}
+export interface CleanupSessionReport {
+    sessionId: string;
+    path: string;
+    status: "preview" | "cleaned" | "skipped" | "failed";
+    reason?: string;
+}
+export interface DoctorCleanupReport {
+    cwd: string;
+    cutoffMs: number;
+    olderThanDays: number;
+    yes: boolean;
+    sessions: readonly CleanupSessionReport[];
+    candidates: readonly CleanupRunResult[];
+    skipped: readonly CleanupRunResult[];
+    deleted: readonly CleanupRunResult[];
+    failures: readonly CleanupFailure[];
+}
+export declare function doctorCleanup(options?: DoctorCleanupOptions): Promise<DoctorCleanupReport>;
+export declare function doctorCleanupExitCode(report: DoctorCleanupReport): 0 | 1;
+export declare function formatDoctorCleanupReport(report: DoctorCleanupReport): string;