export type LockKind = 'task' | 'chat' | 'doc' | 'board' | 'build' | 'orchestrator' | 'tool' /** Blog authoring session (IMP-9xx). */ | 'blog' /** Insights harness session (2026-10). */ | 'insight' /** Custom workflow session (2026-10). */ | 'workflow' /** Workflow authoring session (2026-10): the definition conversation. */ | 'workflow-author'; export interface AgentLock { pid: number; startedAt: string; kind: LockKind; taskId?: string; projectId?: string; documentId?: string; /** Board assistant session target (kind === 'board'). */ boardId?: string; /** BlogGeneration id (kind === 'blog'). */ blogGenerationId?: string; /** InsightNarrativeRun id (kind === 'insight'). */ insightRunId?: string; /** WorkflowRun id (kind === 'workflow'). */ workflowRunId?: string; /** Workflow definition id (kind === 'workflow-author'). */ workflowId?: string; } export declare const LOCK_DIR: string; /** Max session age before lock is considered stale (PID reuse safety net). * Primary liveness signal is pidAlive(); this is a fallback. Configurable * via TEAMSHARE_LOCK_MAX_SESSION_MS env var (ms). Default 24h — long enough * for orchestrator builds that can run 6h+. */ export declare const MAX_SESSION_MS: number; export declare const LOCK_POLL_MS = 10000; export declare const LOCK_MAX_WAIT_MS: number; export declare function lockPath(agentId: string): string; /** * The holder, or null. Returns null both for "free" and for "unreadable", * which callers that must not race (see `isLockBusy`) should obtain from * `readLockFile` instead. */ export declare function readLock(agentId: string): AgentLock | null; /** One-shot acquire: ok=true on success, ok=false + busy set when held. */ export declare function tryAcquireLock(agentId: string, kind: LockKind, meta?: Omit): { ok: boolean; busy?: AgentLock; writeFailed?: string; }; /** Release the lock, but only if we hold it (pid match). */ export declare function releaseLock(agentId: string): void; /** Remove the lock unconditionally (manual override, `clear-lock`). */ export declare function clearLock(agentId: string): void; /** * Staleness-aware busy check for the daemon / probe: the agent is busy only * while the lock is held by a LIVE pid and younger than MAX_SESSION_MS. A * crashed session (dead pid) or an expired lock does NOT block - the queue * flush can spawn immediately instead of stalling on a dead lock. */ export declare function isLockBusy(agentId: string): boolean; /** * Wait until the lock is free, then acquire it. Used by the CLI when a * session starts so a manual run waits for the daemon-spawned session (and * vice versa). Returns the acquired lock, or null when maxWaitMs elapses. * * ── WHY A SAME-TASK RUN IS REFUSED IMMEDIATELY ─────────────────────────────── * * The lock is keyed per AGENT, and `taskId` is inert metadata that nothing ever * compared. So when the same task was dispatched twice (which happens whenever * the fan-out is not suppressed - see `wake-claim.ts`), the second process * waited out the full `LOCK_MAX_WAIT_MS` of SIX HOURS for a lock that was never * going to be released in any useful sense, holding a node process, a spawn * watchdog timer and a mirror lease the entire time. Two observed processes were * parked exactly this way, printing `waiting for it to finish...` once every 10 * seconds, long after the task itself was finished. * * A duplicate is not a conflict to wait out, it is a wake that should never have * been spawned: the incumbent already owns the task, so the correct answer is to * exit at once and say why. Only work on a DIFFERENT task genuinely needs to * wait for the agent to free up. */ export declare function acquireLock(agentId: string, kind: LockKind, meta?: Omit, opts?: { pollMs?: number; maxWaitMs?: number; onWaiting?: (busy: AgentLock) => void; /** * The incumbent already holds THIS task, so waiting cannot help. Returning * null here is the difference between exiting in milliseconds and parking * a process for `LOCK_MAX_WAIT_MS`. */ onDuplicate?: (busy: AgentLock) => void; }): Promise;