/** Minimal API surface — only what the report needs. */ export interface StopSaveApi { addComment(dto: { taskId: string; body: string; }): Promise; } export type StopSaveLog = (text: string, level?: 'stdout' | 'stderr') => void; export interface StopSaveResult { /** Something was actually attempted (a task-run mirror was found). */ handled: boolean; /** The tree was fully removed. */ cleared: boolean; /** Uncommitted work was committed before removal. */ rescued: boolean; /** Every rescue commit reached the remote. */ pushed: boolean; /** At least one rescue commit is local-only. */ localOnly: boolean; branch?: string; rescuedRepos: string[]; localOnlyRepos: string[]; /** Trees that were kept because a rescue failed (the sweep will retry). */ keptPaths: string[]; error?: string; /** * The once-only key this stop announced under (2026-10). The caller passes it * to `postBridgeNotice` as the `clientRequestId`, so the stop announcement is * deduplicated BOTH locally (the latch above, which stops the re-detach) and * server-side (which stops a lost-response retry from duplicating the comment). */ noticeKey?: string; } /** * The task-run mirror a stop should save, or `null` when there is nothing to do. * * `null` covers every case we must NOT touch: no lease (not an isolated run, or * a linked-folder run), a tree that is gone, a tree with a live presence or a * live lease holder. */ export declare function resolveStoppedMirror(taskId: string | null | undefined, opts?: { skipPids?: number[]; agentId?: string; log?: StopSaveLog; }): { path: string; branch?: string; createdAt?: string; } | null; /** * Commit a stopped run's uncommitted work to its task branch and remove the * tree. Never throws: a stop must not fail because cleanup failed. * * IDEMPOTENT PER TREE (2026-10). `saveStoppedRun` is reachable from every * `session.stop` wake, and a wake can be replayed: the reconnect drain, the * stranded sweep and the queue drain all re-deliver stops. Because a FAILED * commit leaves the tree on disk, `resolveStoppedMirror` kept finding the same * lease on every replay, so each one re-attempted the same failing detach and * re-posted the same `[work stopped]` comment. Observed eight times in two * minutes on one task. * * The latch is claimed on the TREE, so a replay is a no-op while a genuinely * separate stop of a different tree still runs. Once a tree is kept, retrying it * is the LEASE SWEEPER's job (it owns the 30-minute and 6-hour passes and has * the right backoff); a wake announces the stop and gets out of the way. */ export declare function saveStoppedRun(taskId: string | null | undefined, agentId: string, api: StopSaveApi | null, log: StopSaveLog, opts?: { skipPids?: number[]; }): Promise; /** The task comment a human reads to learn where the work went. */ export declare function stopSaveComment(taskId: string, res: StopSaveResult): string | null;