export interface MirrorLease { taskId: string; /** Absolute mirror path (`/../.teamshare-worktrees/taskrun-`). */ path: string; /** The linked folder the mirror was created from. */ folder: string; agentId?: string; createdAt: string; /** * Set by the spawned session when it takes the tree. Null while the daemon * still owns the tree (created but not yet handed to a process). */ handedTo?: { pid: number; startedAt: string; kind?: string; } | null; /** * When this tree last changed HANDS - handed to a session, or adopted by a * retry. The reclaim clock reads THIS, never `createdAt`. * * Why it exists (2026-10): `createdAt` is written once, when the mirror is * created, and never moves. So a task that runs for two hours hands a lease * whose "age" is already two hours, and the age gate reads a LONG-RUNNING * tree as abandoned. Worse, `markMirrorAdopted` nulls `handedTo` (correctly - * the dead owner is gone) and that was the ONLY timestamp of the new * ownership, so adopting a tree erased the fact that anyone had just claimed * it. A sweep landing in that window found: no live pid, no presence row * (presence is written by the CLI process only, so a dead CLI means no row * even while the harness is still working), and an hour-old `createdAt` - * and deleted a live session's tree out from under it. * * So ownership now carries its own clock, and a tree that changed hands * recently is never reclaimable no matter how old its root is. Absent on * leases written before this field existed, which fall back to `createdAt`. */ lastActivityAt?: string; /** * A FAILED run keeps its tree so the retry can adopt it (dirty files intact). * The 6h sweeper reclaims it if no retry ever arrives. */ keptForRetry?: boolean; keptAt?: string; /** Set when a retry adopted a dead run's tree instead of creating a new one. */ adopted?: { at: string; dirtyFiles: number; previousAgentId?: string; /** * Worktrees the marker still listed but that no longer EXIST on disk. * * A deleted worktree used to read as "0 uncommitted files", because the * dirty count skips anything missing - so an adopt over a half-destroyed * mirror reported a clean 5-repo tree and the session started inside the * wreckage. Recorded so the caller can say so out loud instead of inferring * health from a number that cannot distinguish "clean" from "gone". */ missingRepos?: string[]; }; /** * The branch this run's work is delivered on (`/`). Mirrors * the marker's `deliverableBranch` so a process that only has the LEASE — the * stop handler, which never reads the marker — can still rescue a killed run's * uncommitted work onto the branch a re-run will check out. */ deliverableBranch?: string; } export declare function readMirrorLease(taskId: string): MirrorLease | null; export declare function writeMirrorLease(lease: MirrorLease): void; /** Merge a patch into an existing lease. No-op when the lease is gone. */ export declare function patchMirrorLease(taskId: string, patch: Partial): MirrorLease | null; export declare function deleteMirrorLease(taskId: string): void; export declare function markMirrorHandedTo(taskId: string, info: { pid: number; kind?: string; }): void; /** * Heartbeat for a dispatched-but-waiting session (2026-10). * * A CLI spawned into a mirror can wait on the agent lock for a long time * (several sessions, one agent) before it ever reaches `claimMirrorForSession`. * During that whole wait the lease reads "never handed to anyone, ageing since * creation" - indistinguishable from an orphan - so a sweep reaps a tree whose * session is already on its way. Touching `lastActivityAt` while waiting keeps * the reclaim clock (30-min grace when the field exists) moving with the waiter. * No-op when the lease is gone; never throws. */ export declare function touchMirrorLease(taskId: string): void; export declare function markMirrorKeptForRetry(taskId: string, reason?: string): void; /** * A retry took over a dead run's tree. * * `handedTo` is nulled because the previous owner really is gone, and * `keptForRetry` is cleared because the retry has now taken that responsibility. * `lastActivityAt` is the load-bearing part: adopting IS a change of hands, and * without it this call would erase the only evidence that the tree was just * claimed, leaving the reclaim clock reading the mirror's original creation time. */ export declare function markMirrorAdopted(taskId: string, info: { dirtyFiles: number; previousAgentId?: string; missingRepos?: string[]; /** * The agent whose run now owns the tree (2026-11-05). * * A stop is routed by TASK id and only `lease.agentId` says whose run built * the tree, so a handover (task reassigned to another agent, or a retry by a * different agent) must move this field too. Without it the adopting agent's * own stop would be refused and the previous agent's stale stop would be * accepted - exactly reversed. */ agentId?: string; }): void; /** Every lease on this machine (the sweeper iterates these, not the folders). */ export declare function listMirrorLeases(): MirrorLease[]; /** * True when something is genuinely USING this mirror right now. * * Two independent signals, either of which is enough: a live pid in the lease, * or a live presence entry in the tree. Both are required to be absent before * a reclaim - that is the whole point of the record (the old sweeper trusted * presence alone, so a lost presence row made it delete live work). */ export declare function mirrorLeaseIsLive(lease: MirrorLease): boolean; /** Age floor before a never-handed-off lease may be reclaimed (anti-race). */ export declare const ORPHAN_RECLAIM_MIN_AGE_MS: number; /** * How long a tree that recently CHANGED HANDS is protected from a sweep (2026-10). * * THE BUG THIS EXISTS FOR. The 30-minute lease sweep decided a mirror was * abandoned, then took several minutes to walk every other project's worktrees * before it reached this one - and `detachIsolationMirror` did not re-check * anything when it finally got there. In that gap a retry adopted the tree and a * session started working in it. Every liveness signal the sweeper had read was * true when it read it and false by the time it acted: no live pid (the adopt * had just nulled it), no presence row (presence is written by the CLI process * only, and the new CLI had not started yet), and `createdAt` two hours old * because it is written once and never moves. The sweep deleted ~1 GB of a live * session's tree. * * So: a lease whose `lastActivityAt` is recent is NEVER reclaimable, whatever * its root's age and whatever the pid and presence say. The interval is the fast * sweep's own cadence, so the cost is "a dead tree lives at most one extra * sweep" and the benefit is that the window scales with the sweep instead of * with how long the human's task happens to have been running. * * Applies to FUTURE runs only, by construction: it reads the lease's own * timestamps, so a mirror that was already mishandled is not retroactively * judged by it - it is simply never judged twice. */ export declare const RECLAIM_GRACE_MS: number; /** * A lease is reclaimable when nothing is using the tree, it is not held for a * retry, and it is old enough that no spawn can still be in flight. * * THE CLOCK IS `lastActivityAt` WHEN IT EXISTS. `createdAt` is the creation * time, so it keeps growing for the whole life of the tree and reads a * long-running task as abandoned - which is precisely backwards. A lease written * before `lastActivityAt` existed falls back to `createdAt` under the original * floor, so old leases keep their old (shorter) grace rather than being judged * by a field they never had. */ export declare function mirrorLeaseIsReclaimable(lease: MirrorLease, now?: number): boolean;