@ikarmic/forge-core 5.2.0 → 5.4.0

package/dist/types.d.ts

@@ -107,12 +107,45 @@ export interface ToolContext {
      * the default `child_process` runner.
      */
     commandRunner?: CommandRunner;
+    /** How long `search_files` may match before its worker is stopped. Default 20 s. */
+    searchTimeoutMs?: number;
+    /** Run `run_command` inside the OS sandbox (`AgentConfig.commandSandbox`); handed to sub-agents. */
+    commandSandbox?: CommandSandbox;
     /** The model sub-agents use instead of the parent's (`AgentConfig.subAgentModel`). */
     subAgentModel?: ModelConfig;
     /** Folder `AGENTS.md` paths already shown in this run; `read_file` adds each folder's file once. */
     shownFolderInstructions?: Set<string>;
     /** Longest output `run_command` returns per stream before cutting the middle (`AgentConfig.maxToolOutputChars`). */
     maxOutputChars?: number;
+    /**
+     * Folders outside the project that READ tools may also reach: a repository this run cloned with `repo_clone`.
+     * Added to by that tool only; write tools never see them (shared.ts `resolveSafePath` `read` option). Not handed to a child.
+     */
+    readRoots?: string[];
+    /**
+     * Asks whether a directory outside the project may be read (G16). Given the real directory, after links. Absent: such a
+     * path is refused. Not handed to a child, which has no one to ask.
+     */
+    askReadOutside?: (dir: string) => boolean | Promise<boolean>;
+    /** Directories the person already refused in this run, so they are not asked again. */
+    deniedReadDirs?: Set<string>;
+    /** Where `repo_clone` keeps repositories (default `~/.forge/cache/repos`). `testGitConfig` is for tests only. */
+    repoCache?: {
+        root: string;
+        testGitConfig?: string[];
+    };
+    /** A chat can ask the person about planning first (`AgentConfig.suggestPlan`). */
+    suggestPlan?: boolean;
+    /** The person already chose "just do it" for this request (`AgentConfig.planDeclined`). */
+    planDeclined?: boolean;
+    /** Which shell the default `run_command` runner uses (`AgentConfig.shell`). */
+    shell?: import('./tools/shell.js').ShellPreference;
+    /** The chat's wakeup scheduler (`AgentConfig.wakeups`); never handed to a child. */
+    wakeups?: import('./wakeup/wakeup.js').WakeupScheduler;
+    /** The run's background processes (`bg_start`); the agent stops them when the run ends. Never handed to a child. */
+    processes?: import('./tools/background-process.js').BackgroundProcesses;
+    /** Language servers for `get_diagnostics` (`AgentConfig.verify.lsp` when it is an object). */
+    lspConfig?: import('./lsp/index.js').LspConfig;
     /** Asks the person a question (`ask_user`); absent when no surface can answer. */
     askUser?: (question: UserQuestion, signal?: AbortSignal) => Promise<string>;
     /**
@@ -176,6 +209,23 @@ export type ModelRouter = (ctx: {
     /** Tool names the model called on the previous step (empty on the first). */
     lastToolNames: string[];
 }) => ModelConfig | undefined;
+/** What `run_command`'s OS sandbox allows besides writing to the workspace and the temp folder. */
+export interface CommandSandbox {
+    /** Let commands reach the network. */
+    network: boolean;
+    /** More folders commands may write to (a package manager's cache, say). */
+    extraWritable?: string[];
+    /**
+     * With the network off: hosts Forge's own network tools (fetch_url, repo_clone, the browser, GitHub, web search with `*`) may still
+     * reach. Exact names, `*.example.com`, or `*`. Shell commands are all or nothing and ignore it (F13).
+     */
+    allowedHosts?: string[];
+    /**
+     * The surface told the person this system cannot confine commands (Windows has no sandbox tool) and they go on anyway.
+     * Without it such a command is refused rather than run unconfined in silence.
+     */
+    allowUnconfined?: boolean;
+}
 /**
  * Executes one shell command on behalf of `run_command`. Return `null` to decline
  * (e.g. no terminal available); the default `child_process` runner then handles it.
@@ -250,6 +300,11 @@ export interface ChildProgressEvent {
     /** Any event the child emitted. */
     event: AgentEvent;
 }
+/**
+ * How a tool call was let through: the person approved it, a permission rule allowed it, it is on the
+ * auto-approve list, memory writes are allowed, the command is on the "Always allow" list, or the run is Autonomous.
+ */
+export type ApprovalSource = 'person' | 'rule' | 'list' | 'memory' | 'always' | 'autonomous';
 /** Streamed agent event: surfaced to the UI via the AgentRunOptions.onEvent callback. */
 export type AgentEvent = {
     type: 'text_delta';
@@ -263,11 +318,14 @@ export type AgentEvent = {
 } | {
     type: 'reasoning_done';
     text: string;
-} | {
+}
+/** `approval` says how the call was let through; absent for bookkeeping tools that never ask (the todo list). */
+ | {
     type: 'tool_call';
     name: string;
     id: string;
     args: unknown;
+    approval?: ApprovalSource;
 } | {
     type: 'tool_result';
     name: string;
@@ -343,6 +401,22 @@ export type AgentEvent = {
 } | {
     type: 'continuation'; /** 1-based count of continuations so far in this run. */
     count: number;
+}
+/**
+ * The step now running failed (a provider error worth retrying, or an empty reply) and is being asked again after
+ * `delayMs`. Everything it streamed is discarded: a UI drops the step's partial text.
+ */
+/** The model ended a turn with `open` items of its own todo list still open and was reminded once (RB-44). */
+ | {
+    type: 'todo_nudge';
+    open: number;
+} | {
+    type: 'retry';
+    kind: 'provider_error' | 'empty_reply' | 'offline';
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+    reason: string;
 } | {
     type: 'phase';
     /** Architect/editor mode: which phase the following events belong to. */
@@ -630,6 +704,7 @@ export interface AgentConfig {
     maskOldResults?: boolean | {
         keepRecentTurns?: number;
         minChars?: number;
+        protectTokens?: number;
     };
     /**
      * Model to use for the summarizer. Defaults to the agent's own model.
@@ -682,6 +757,10 @@ export interface AgentConfig {
         extensions?: string[];
         minScore?: number;
         defaultLimit?: number;
+        /** Asked before code is sent to a remote embedder (F12). Absent: no question. */
+        consent?: import('./semantic/semantic-index.js').SemanticOptions['consent'];
+        /** Progress of the index, for a status item. */
+        onStatus?: import('./semantic/semantic-index.js').SemanticOptions['onStatus'];
     };
     /**
      * After the model finishes a run that edited files, run these commands and
@@ -719,6 +798,31 @@ export interface AgentConfig {
      * linter commands) and append any problems to the tool result so the model fixes them.
      */
     autoLint?: import('./lint/auto-lint.js').AutoLintConfig;
+    /**
+     * After a file is written, run the person's formatter for its type on it (`prettier --write`), before auto-lint, and tell
+     * the model when the file changed. The commands run on every edit without asking, so they come from the person only (RB-12).
+     */
+    autoFormat?: import('./format/auto-format.js').AutoFormatConfig;
+    /** The surface shows a "plan first?" card after a run that called `suggest_plan`. Without it the tool says to carry on. */
+    suggestPlan?: boolean;
+    /** The person already answered "just do it": `suggest_plan` says to carry on instead of asking again. */
+    planDeclined?: boolean;
+    /** Folders outside the project that read tools may reach from the start of the run: what the person allowed earlier in this chat (G16). */
+    readRoots?: string[];
+    /** Asks the person whether a directory outside the project may be read; absent = such a path is refused. */
+    askReadOutside?: (dir: string) => boolean | Promise<boolean>;
+    /** Which shell Forge's own `run_command` runner uses on Windows. Default `auto`: pwsh, Windows PowerShell, Git Bash, cmd.exe. */
+    shell?: import('./tools/shell.js').ShellPreference;
+    /**
+     * The shell commands really run in when a surface supplies its own runner (VS Code's terminal), so the prompt can say so
+     * (RB-27). Without it a custom runner is described as the platform default.
+     */
+    runnerShell?: import('./tools/shell.js').ShellKind;
+    /**
+     * The chat's scheduler for `schedule_wakeup` / `cancel_wakeup`. Lives longer than a run: the surface creates it once per
+     * chat, delivers a due wakeup as an automatic message, and disposes it. Absent = the tools are not offered.
+     */
+    wakeups?: import('./wakeup/wakeup.js').WakeupScheduler;
     /**
      * Stop the run (`reason: 'budget_exceeded'`) once the running USD cost reaches
      * this cap. Checked before each model call, so one in-flight turn can overshoot.
@@ -742,6 +846,23 @@ export interface AgentConfig {
      * Each continuation is a normal iteration (counts toward every cap).
      */
     maxContinuations?: number;
+    /**
+     * Retrying a step whose model call failed with something a retry can fix (429, 5xx, overload, dropped
+     * connection). Default 5 retries, back-off from 2 s (doubling, capped at 30 s) unless the provider sends
+     * retry-after. An empty or reasoning-only reply is asked for again twice, separately.
+     */
+    providerRetry?: {
+        maxRetries?: number;
+        baseDelayMs?: number;
+        /**
+         * With no network at all (DNS or route gone) the run waits instead of spending retries: it probes every
+         * `offlinePollMs` (default 3 s) for up to `maxOfflineMs` in total (default 15 min), then reports the error.
+         */
+        offlinePollMs?: number;
+        maxOfflineMs?: number;
+        /** True when the network is reachable; default dials a few public addresses over TCP. */
+        networkProbe?: () => Promise<boolean>;
+    };
     /**
      * Pick the model for each step (cheap for exploration, strong for planning…).
      * Return `undefined` to keep the current model. Cost is priced per routed model.
@@ -749,6 +870,11 @@ export interface AgentConfig {
     modelRouter?: ModelRouter;
     /** Replace how `run_command` executes. See {@link CommandRunner}. */
     commandRunner?: CommandRunner;
+    /**
+     * Confine `run_command` with the OS sandbox: bubblewrap on Linux, sandbox-exec on macOS. A command is refused when
+     * the tool is missing; Windows has no equivalent, so there commands run as before. Absent = off.
+     */
+    commandSandbox?: CommandSandbox;
     /**
      * Answers `ask_user`. When absent, or when `auto` is on, the model is not offered the tool.
      */
@@ -887,6 +1013,11 @@ export interface AgentRunResult {
      * across turns (used by the REPL).
      */
     messages: ModelMessage[];
+    /**
+     * This run's own messages: its user message and everything added after it, untouched by compaction (RB-58).
+     * Append them to a display transcript; `messages` is what the next turn should send.
+     */
+    turnMessages: ModelMessage[];
 }
 /** Public alias for the AI SDK language model handle. */
 export type AnyLanguageModel = LanguageModel;

package/dist/wakeup/wakeup-tools.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const scheduleParams: z.ZodObject<{
+    reason: z.ZodString;
+    delay: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const scheduleWakeupTool: ToolDefinition<z.infer<typeof scheduleParams>, {
+    id: string;
+    dueAt: string;
+    notice?: string;
+    note: string;
+}>;
+declare const cancelParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const cancelWakeupTool: ToolDefinition<z.infer<typeof cancelParams>, {
+    id: string;
+    cancelled: boolean;
+}>;
+export {};

package/dist/wakeup/wakeup-tools.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+function scheduler(ctx) {
+    if (!ctx.wakeups)
+        throw new Error('Scheduled wakeups are not available here.');
+    return ctx.wakeups;
+}
+const scheduleParams = z.object({
+    reason: z.string().min(1).describe('Why you want to be woken, in one sentence. You will see it again when the time comes.'),
+    delay: z.string().optional().describe('How long to wait: a number of seconds, or 30s, 5m, 2h, 1d. Give this or when.'),
+    when: z.string().optional().describe('An exact time as ISO date and time, for example 2026-10-27T15:30:00. Give this or delay.'),
+    prompt: z.string().optional().describe('What you will do when woken, in your own words.'),
+});
+export const scheduleWakeupTool = {
+    name: 'schedule_wakeup',
+    description: 'Ask to be woken once, later, for example to check on a build or a background process. At the time you get an automatic message with your reason. ' +
+        'It works only while the editor is open (a closed editor wakes you when it is next opened), one time per call, at least 10 seconds and at most 7 days ahead, and a chat holds at most 10.',
+    parameters: scheduleParams,
+    execute: async (args, ctx) => {
+        const w = await scheduler(ctx).schedule(args);
+        return {
+            id: w.id,
+            dueAt: new Date(w.dueAt).toISOString(),
+            ...(w.notice ? { notice: w.notice } : {}),
+            note: 'Scheduled. Finish what you are doing now; do not wait for it.',
+        };
+    },
+};
+const cancelParams = z.object({ id: z.string().describe('The id returned by schedule_wakeup.') });
+export const cancelWakeupTool = {
+    name: 'cancel_wakeup',
+    description: 'Cancel a wakeup you scheduled with schedule_wakeup, before it fires.',
+    parameters: cancelParams,
+    execute: async (args, ctx) => ({ id: args.id, cancelled: await scheduler(ctx).cancel(args.id) }),
+};

package/dist/wakeup/wakeup.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Scheduled wakeups: the model asks to be woken later ("check the build in 10 minutes") and the chat delivers an
+ * automatic message when the time comes. The scheduler belongs to the chat, not to a run, and works only while the
+ * editor is open. Caps follow Kilo's wakeup/schema.ts; recurring (cron) wakeups are not offered.
+ */
+/** A delay under this is raised to it; an absolute time is honoured as given. */
+export declare const MIN_DELAY_MS = 10000;
+/** A wakeup never fires further out than seven days. */
+export declare const MAX_HORIZON_MS: number;
+/** One chat holds at most this many pending wakeups. */
+export declare const MAX_PER_SESSION = 10;
+export interface Wakeup {
+    id: string;
+    /** Why the model wants to be woken; shown to the model again and to the person. */
+    reason: string;
+    /** What to do when woken, in the model's own words. */
+    prompt?: string;
+    /** Epoch milliseconds. */
+    dueAt: number;
+    created: number;
+}
+/** Where pending wakeups are kept so they survive a reload of the editor. */
+export interface WakeupStore {
+    load(): Promise<Wakeup[]>;
+    save(wakeups: Wakeup[]): Promise<void>;
+}
+/** When a wakeup is due, with the clamp that applied (as a sentence for the model), or an error naming the problem. */
+export declare function resolveWakeupTime(input: {
+    delay?: string;
+    when?: string;
+}, now?: number): {
+    dueAt: number;
+    notice?: string;
+};
+export interface WakeupSchedulerOptions {
+    /** Deliver a due wakeup. Return false when the chat is busy: it is offered again after `retryMs`. */
+    onDue: (wakeup: Wakeup) => Promise<boolean>;
+    store?: WakeupStore;
+    retryMs?: number;
+}
+export declare class WakeupScheduler {
+    private readonly options;
+    private readonly pending;
+    private readonly timers;
+    private nextId;
+    private disposed;
+    private readonly retryMs;
+    constructor(options: WakeupSchedulerOptions);
+    list(): Wakeup[];
+    schedule(input: {
+        delay?: string;
+        when?: string;
+        reason: string;
+        prompt?: string;
+    }): Promise<Wakeup & {
+        notice?: string;
+    }>;
+    cancel(id: string): Promise<boolean>;
+    cancelAll(): Promise<void>;
+    /** Load what a previous window left; anything already due fires on the next tick. */
+    restore(): Promise<void>;
+    /** Stop every timer without forgetting what is stored (the editor is closing, or the chat was deleted elsewhere). */
+    dispose(): void;
+    private arm;
+    private disarm;
+    private fire;
+    private save;
+}
+/**
+ * The automatic message a due wakeup becomes. It is a user-role message, so it says what it is and that the person's
+ * own words win: the first wording of the todo nudge ("carry on now") overrode "wait for my go-ahead" in live runs (RB-44).
+ */
+export declare function wakeupMessage(w: Pick<Wakeup, 'reason' | 'prompt' | 'created' | 'dueAt'> & {
+    id?: string;
+}): string;

package/dist/wakeup/wakeup.js

@@ -0,0 +1,151 @@
+/**
+ * Scheduled wakeups: the model asks to be woken later ("check the build in 10 minutes") and the chat delivers an
+ * automatic message when the time comes. The scheduler belongs to the chat, not to a run, and works only while the
+ * editor is open. Caps follow Kilo's wakeup/schema.ts; recurring (cron) wakeups are not offered.
+ */
+/** A delay under this is raised to it; an absolute time is honoured as given. */
+export const MIN_DELAY_MS = 10_000;
+/** A wakeup never fires further out than seven days. */
+export const MAX_HORIZON_MS = 7 * 24 * 60 * 60 * 1000;
+/** One chat holds at most this many pending wakeups. */
+export const MAX_PER_SESSION = 10;
+/** How often a due wakeup is offered again while the chat is busy. */
+const DEFAULT_RETRY_MS = 15_000;
+// ISO-8601 date-time; without an offset the wall clock is read in the host's timezone.
+const WHEN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/;
+// `30`, `30s`, `5m`, `2h`, `1d`; a bare number is seconds.
+const DELAY = /^\s*(\d+)\s*([smhd])?\s*$/i;
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** When a wakeup is due, with the clamp that applied (as a sentence for the model), or an error naming the problem. */
+export function resolveWakeupTime(input, now = Date.now()) {
+    const delay = input.delay?.trim() || undefined;
+    const when = input.when?.trim() || undefined;
+    if ((delay !== undefined) === (when !== undefined))
+        throw new Error('Provide exactly one of delay or when.');
+    if (when !== undefined) {
+        const target = WHEN.test(when) ? Date.parse(when) : NaN;
+        if (!Number.isFinite(target))
+            throw new Error(`Invalid time: ${when}. Use an ISO date and time such as 2026-10-27T15:30:00.`);
+        if (target <= now)
+            throw new Error(`Wakeup time is not in the future: ${when}`);
+        if (target > now + MAX_HORIZON_MS)
+            return { dueAt: now + MAX_HORIZON_MS, notice: `Requested time "${when}" is beyond the 7-day limit and was pulled back to it.` };
+        return { dueAt: target };
+    }
+    const m = DELAY.exec(delay);
+    if (!m)
+        throw new Error(`Invalid delay: ${delay}. Use a number of seconds, or 30s, 5m, 2h, 1d.`);
+    const span = Number(m[1]) * UNIT_MS[(m[2]?.toLowerCase() ?? 's')];
+    if (span <= 0)
+        throw new Error(`Wakeup delay is not in the future: ${delay}`);
+    if (span < MIN_DELAY_MS)
+        return { dueAt: now + MIN_DELAY_MS, notice: `Requested delay "${delay}" is under the 10-second minimum and was raised to it.` };
+    if (span > MAX_HORIZON_MS)
+        return { dueAt: now + MAX_HORIZON_MS, notice: `Requested delay "${delay}" is beyond the 7-day limit and was pulled back to it.` };
+    return { dueAt: now + span };
+}
+export class WakeupScheduler {
+    options;
+    pending = new Map();
+    timers = new Map();
+    nextId = 1;
+    disposed = false;
+    retryMs;
+    constructor(options) {
+        this.options = options;
+        this.retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+    }
+    list() {
+        return [...this.pending.values()].sort((a, b) => a.dueAt - b.dueAt);
+    }
+    async schedule(input) {
+        if (this.pending.size >= MAX_PER_SESSION)
+            throw new Error(`A chat can hold at most ${MAX_PER_SESSION} pending wakeups. Cancel one first.`);
+        const now = Date.now();
+        const { dueAt, notice } = resolveWakeupTime(input, now);
+        const wakeup = { id: `wk${this.nextId++}-${now.toString(36)}`, reason: input.reason, ...(input.prompt ? { prompt: input.prompt } : {}), dueAt, created: now };
+        this.pending.set(wakeup.id, wakeup);
+        this.arm(wakeup);
+        await this.save();
+        return notice ? { ...wakeup, notice } : wakeup;
+    }
+    async cancel(id) {
+        if (!this.pending.delete(id))
+            return false;
+        this.disarm(id);
+        await this.save();
+        return true;
+    }
+    async cancelAll() {
+        for (const id of [...this.pending.keys()])
+            this.disarm(id);
+        this.pending.clear();
+        await this.save();
+    }
+    /** Load what a previous window left; anything already due fires on the next tick. */
+    async restore() {
+        const saved = (await this.options.store?.load().catch(() => [])) ?? [];
+        for (const w of saved) {
+            if (this.pending.has(w.id))
+                continue;
+            this.pending.set(w.id, w);
+            this.arm(w);
+        }
+    }
+    /** Stop every timer without forgetting what is stored (the editor is closing, or the chat was deleted elsewhere). */
+    dispose() {
+        this.disposed = true;
+        for (const id of [...this.timers.keys()])
+            this.disarm(id);
+    }
+    arm(w, delayMs = Math.max(0, w.dueAt - Date.now())) {
+        this.disarm(w.id);
+        if (this.disposed)
+            return;
+        const timer = setTimeout(() => void this.fire(w), delayMs);
+        timer.unref?.();
+        this.timers.set(w.id, timer);
+    }
+    disarm(id) {
+        const t = this.timers.get(id);
+        if (t)
+            clearTimeout(t);
+        this.timers.delete(id);
+    }
+    async fire(w) {
+        this.timers.delete(w.id);
+        if (!this.pending.has(w.id))
+            return;
+        let delivered = false;
+        try {
+            delivered = await this.options.onDue(w);
+        }
+        catch {
+            delivered = false;
+        }
+        if (!this.pending.has(w.id))
+            return;
+        if (!delivered) {
+            this.arm(w, this.retryMs);
+            return;
+        }
+        this.pending.delete(w.id);
+        await this.save();
+    }
+    async save() {
+        await this.options.store?.save(this.list()).catch(() => undefined);
+    }
+}
+/**
+ * The automatic message a due wakeup becomes. It is a user-role message, so it says what it is and that the person's
+ * own words win: the first wording of the todo nudge ("carry on now") overrode "wait for my go-ahead" in live runs (RB-44).
+ */
+export function wakeupMessage(w) {
+    const minutes = Math.max(1, Math.round((w.dueAt - w.created) / 60_000));
+    return [
+        `This is an automatic message, not a message from the user. Earlier in this chat you asked to be woken after about ${minutes} minute${minutes === 1 ? '' : 's'}.`,
+        `Reason: ${w.reason}`,
+        ...(w.prompt ? [`What you planned to do: ${w.prompt}`] : []),
+        'Carry on with that now, unless the user has asked you to stop or wait since then. If they have, leave it and say nothing about this message.',
+    ].join('\n');
+}

package/dist/worktree/health.d.ts

@@ -0,0 +1,51 @@
+export interface ListedWorktree {
+    path: string;
+    head: string;
+    /** Short branch name, absent when detached. */
+    branch?: string;
+    detached: boolean;
+    locked: boolean;
+    lockReason?: string;
+    /** Git says its folder is gone and it can be pruned. */
+    prunable: boolean;
+}
+/** `git worktree list --porcelain` into entries. */
+export declare function parseWorktreeList(text: string): ListedWorktree[];
+export interface WorktreeInspection {
+    /** Worktrees git lists under `.forge/worktrees`. */
+    registered: ListedWorktree[];
+    /** Folders under `.forge/worktrees` that git does not list. */
+    strayFolders: string[];
+    /** Listed worktrees whose folder is gone. */
+    missing: ListedWorktree[];
+}
+export declare function inspectWorktrees(repoRoot: string): Promise<WorktreeInspection>;
+export interface HealthFinding {
+    path: string;
+    /** What is wrong, in a sentence. */
+    problem: string;
+    /** What to do about it, in a sentence. */
+    advice?: string;
+    /** A fix Forge can make itself, after the person confirms: forget a listing, or delete a stray folder. */
+    fix?: 'prune' | 'delete-folder';
+}
+/** Read-only checks of every Agent Manager worktree. An empty list means all is well. */
+export declare function doctorWorktrees(repoRoot: string): Promise<HealthFinding[]>;
+export interface WorktreeStats {
+    /** Commits on the session branch that the base does not have. */
+    ahead: number;
+    /** Commits on the base that the session branch does not have. */
+    behind: number;
+    /** Files changed against the base, committed or not. */
+    changed: number;
+    /** Lines added against the base in tracked files, committed or not. A new file git has not been told about is not counted. */
+    added: number;
+    /** Lines removed against the base, counted the same way. */
+    removed: number;
+}
+/** Numbers for one session's row. Never throws; a folder or branch that cannot be read gives zeros. */
+export declare function worktreeStats(repoRoot: string, worktreePath: string, branch: string, base: string): Promise<WorktreeStats>;
+/** Forget listings whose folder is gone. Returns how many of the Agent Manager's were forgotten. */
+export declare function pruneMissingWorktrees(repoRoot: string): Promise<number>;
+/** Delete a folder under `.forge/worktrees` that git does not know. Refuses anything else. */
+export declare function removeStrayFolder(repoRoot: string, dir: string): Promise<void>;