kith-coord 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,983 @@
+import * as node_sqlite from 'node:sqlite';
+import { DatabaseSync } from 'node:sqlite';
+
+interface CoordEvent {
+    id: number;
+    timestamp: number;
+    agent_id: string | null;
+    event_type: string;
+    payload: Record<string, unknown>;
+}
+declare class CoordDatabase {
+    readonly db: DatabaseSync;
+    readonly repoRoot: string;
+    readonly commonGitDir: string | null;
+    readonly isLinkedWorktree: boolean;
+    readonly coordDir: string;
+    readonly dbPath: string;
+    private inTransaction;
+    constructor(repoRoot: string, customDbPath?: string);
+    /** Validate an existing snapshot without migration or ownership changes. */
+    static inspectSchema(db: DatabaseSync): number;
+    private configurePragmas;
+    private static schemaVersion;
+    private static fencingEpoch;
+    private migrate;
+    /**
+     * Executes a synchronous callback inside a `BEGIN IMMEDIATE` transaction
+     * with automatic jittered backoff retries if another process temporarily holds the WAL write lock.
+     */
+    withTransaction<T>(fn: () => T, maxRetries?: number): T;
+    /**
+     * Atomically increments and returns the next monotonic fencing token.
+     */
+    nextFencingToken(): number;
+    currentFencingEpoch(): number;
+    logEvent(agentId: string | null, eventType: string, payload?: Record<string, unknown>): number;
+    getEventsSince(sinceId: number, limit?: number): CoordEvent[];
+    close(): void;
+}
+
+interface AgentRecord {
+    id: string;
+    name: string;
+    client: string;
+    pid: number;
+    pid_start_time: string;
+    pgid: number;
+    worktree_path: string | null;
+    branch: string | null;
+    shadow_tree_sha: string | null;
+    status: 'active' | 'idle' | 'dead' | 'completed';
+    last_seen_event_id: number;
+    registered_at: number;
+    last_heartbeat_at: number;
+    lease_expires_at: number;
+}
+declare class SessionOwnershipError extends Error {
+    constructor(agentId: string);
+}
+declare class StaleFencingTokenError extends Error {
+    readonly resourceId: string;
+    readonly providedToken: number;
+    readonly expectedToken: number;
+    constructor(resourceId: string, providedToken: number, expectedToken: number);
+}
+interface SessionRegistration {
+    agent: AgentRecord;
+    fencingToken: number;
+    sessionToken: string;
+    sessionEpoch: number;
+}
+declare class FencingAndAgentManager {
+    private readonly coordDb;
+    static readonly DEFAULT_LEASE_MS: number;
+    private readonly capabilities;
+    constructor(coordDb: CoordDatabase);
+    static validateLease(duration: number): number;
+    /** A real kernel process identity; tests must not supply liveness sentinels. */
+    static getProcessStartTime(pid: number): string | null;
+    static isProcessAlive(pid: number, expectedStartTime: string): boolean;
+    registerAgent(params: {
+        id: string;
+        name?: string;
+        client?: string;
+        pid?: number;
+        pgid?: number;
+        worktreePath?: string | null;
+        branch?: string | null;
+        leaseDurationMs?: number;
+        sessionToken?: string;
+    }): SessionRegistration;
+    resumeSession(agentId: string, sessionToken: string): number;
+    assertSession(agentId: string, sessionToken?: string | undefined): number;
+    sessionEnvironment(agentId: string): NodeJS.ProcessEnv;
+    heartbeat(agentId: string, leaseDurationMs?: number): AgentRecord;
+    getAgent(agentId: string): AgentRecord | null;
+    listAgents(onlyActive?: boolean): AgentRecord[];
+    reapDeadAgents(): string[];
+    completeAgentSession(agentId: string): void;
+    abandonAgentSession(agentId: string): void;
+    private reclaim;
+    verifyFencingToken(resourceId: string, provided: number, expected: number): void;
+    private hash;
+}
+
+interface SpawnedWorktree {
+    agentId: string;
+    worktreePath: string;
+    branch: string;
+    hydrationMethod: 'apfs-cow' | 'reflink-cow' | 'copy' | 'none';
+    hydratedDirs: string[];
+    durationMs: number;
+}
+declare class CoWWorktreeManager {
+    private readonly coordDb;
+    private readonly fencing;
+    private static readonly HYDRATABLE_DIRS;
+    private static readonly ENV_FILES;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager);
+    /**
+     * Spawns an isolated Git worktree for `agentId` and hydrates `node_modules` / `.env`
+     * using APFS Copy-on-Write (`cp -cR`) on macOS or reflink on Linux (with independent-copy fallback).
+     */
+    spawnWorktree(params: {
+        agentId: string;
+        branch?: string;
+        baseRef?: string;
+    }): SpawnedWorktree;
+    private cloneDirectoryCoW;
+    removeWorktree(agentId: string): boolean;
+    listWorktrees(): Array<{
+        path: string;
+        head: string;
+        branch: string | null;
+    }>;
+}
+
+interface WorktreeChange {
+    status: string;
+    path: string;
+    originalPath?: string;
+}
+declare function worktreeChanges(cwd: string): WorktreeChange[];
+interface WorkspaceObservation {
+    agentId: string;
+    path: string;
+    recordedBranch: string | null;
+    status: AgentRecord['status'];
+    leaseExpired: boolean;
+    lastHeartbeatAt: number;
+    available: boolean;
+    error?: string;
+    branch: string | null;
+    head: string | null;
+    comparisonBase: string | null;
+    dirtyFiles: WorktreeChange[];
+    lastCommitAt: number | null;
+    hoursSinceLastCommit: number | null;
+    ahead: number | null;
+    behind: number | null;
+    overlaps: Array<{
+        path: string;
+        agentIds: string[];
+    }>;
+}
+/** Git observation never stages files, checks out branches, fetches, or refreshes the index. */
+declare function observeWorkspaces(repoRoot: string, agents: AgentRecord[], now?: number): WorkspaceObservation[];
+/** Preview committed inputs only. merge-tree may write unreachable Git objects, never worktree/index/database contents. */
+declare function previewIntegration(repoRoot: string, agent: AgentRecord): {
+    ok: boolean;
+    clean: null;
+    sourceHead: string;
+    targetHead: string;
+    sourceBranch: string;
+    targetBranch: string;
+    conflicts: never[];
+    dirtyFiles: WorktreeChange[];
+    targetDirtyFiles: WorktreeChange[];
+    reason: string;
+    verified?: undefined;
+} | {
+    ok: boolean;
+    clean: boolean;
+    sourceHead: string;
+    targetHead: string;
+    sourceBranch: string;
+    targetBranch: string;
+    conflicts: string[];
+    dirtyFiles: WorktreeChange[];
+    targetDirtyFiles: WorktreeChange[];
+    verified: boolean;
+    reason?: undefined;
+};
+
+type SymbolKind = 'function' | 'type' | 'interface' | 'class' | 'schema' | 'route' | 'const';
+interface ExtractedSymbol {
+    symbolName: string;
+    kind: SymbolKind;
+    signature: string;
+    astHash: string;
+    paramsFingerprint: string;
+    docComment: string;
+}
+interface ExtractedImport {
+    rawSpecifier: string;
+    resolvedPath: string | null;
+    importedSymbols: string[];
+}
+interface FileAstAnalysis {
+    filePath: string;
+    fileHash: string;
+    exports: ExtractedSymbol[];
+    imports: ExtractedImport[];
+}
+declare class AstAnalyzer {
+    /**
+     * Analyzes a source file's content to extract exported contracts (functions, types,
+     * interfaces, schemas, routes) and imported module dependencies.
+     */
+    static analyzeSource(repoRoot: string, filePath: string, sourceContent?: string): FileAstAnalysis;
+    static extractExports(content: string): ExtractedSymbol[];
+    static extractImports(repoRoot: string, sourceRelPath: string, content: string): ExtractedImport[];
+    static resolveRelativeImport(repoRoot: string, sourceRelPath: string, specifier: string): string | null;
+    private static extractBracedBlockSummary;
+    private static extractFieldTypesFingerprint;
+    static computeParamsFingerprint(rawParams: string, rawReturn: string): string;
+    private static normalizeWhitespace;
+    private static hashSignature;
+}
+
+interface LockRecord {
+    id: string;
+    pattern: string;
+    lock_type: 'glob' | 'file' | 'symbol';
+    mode: 'exclusive' | 'shared';
+    owner_agent_id: string;
+    task_id: string | null;
+    fencing_token: number;
+    reason: string;
+    acquired_at: number;
+    expires_at: number;
+}
+interface LockConflict {
+    existingLock: LockRecord;
+    requestedPattern: string;
+    ownerAgentName: string;
+    ownerIntent: string | null;
+}
+interface AcquireLockResult {
+    ok: boolean;
+    fencingToken: number;
+    locks: LockRecord[];
+    conflicts: LockConflict[];
+}
+declare class LockEngine {
+    private readonly coordDb;
+    private readonly fencing;
+    private readonly pathCase;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager);
+    static normalizePattern(repoRoot: string, rawPattern: string): string;
+    static normalizeFile(repoRoot: string, file: string): string;
+    private static literalScope;
+    private rootForAgent;
+    private wildcardHasAliases;
+    /** Exact overlap for the documented scope grammar; legacy unsupported locks block conservatively. */
+    static patternsOverlap(rawA: string, rawB: string): boolean;
+    /**
+     * Atomically acquires locks on one or more file/glob/symbol patterns.
+     * All-or-nothing: if any pattern conflicts with another live agent, no locks are created.
+     */
+    acquireLocks(params: {
+        agentId: string;
+        patterns: string[];
+        mode?: 'exclusive' | 'shared';
+        lockType?: 'glob' | 'file' | 'symbol';
+        taskId?: string | null;
+        reason?: string;
+        leaseDurationMs?: number;
+    }): AcquireLockResult;
+    /**
+     * Checks whether `agentId` is allowed to edit `filePath`.
+     * Also verifies the fencing token if provided.
+     */
+    checkFileWriteAccess(params: {
+        agentId: string;
+        filePath: string;
+        fencingToken?: number;
+    }): {
+        allowed: boolean;
+        reason?: string;
+        conflictingLock?: LockRecord;
+        ownerIntent?: string | null;
+    };
+    releaseLocks(params: {
+        agentId: string;
+        patterns?: string[];
+        fencingToken?: number;
+    }): number;
+    private overlapsExisting;
+    listLocks(): LockRecord[];
+}
+
+interface ContractRecord {
+    id: string;
+    file_path: string;
+    symbol_name: string;
+    kind: SymbolKind;
+    signature: string;
+    ast_hash: string;
+    params_fingerprint: string;
+    doc_comment: string;
+    owner_agent_id: string | null;
+    version: number;
+    is_breaking: boolean;
+    updated_at: number;
+}
+interface BlastRadiusAlert {
+    modifiedFile: string;
+    symbolName: string;
+    previousSignature: string;
+    newSignature: string | null;
+    affectedDownstreamFile: string;
+    hopDistance: number;
+    affectedAgentId: string | null;
+}
+interface FileModificationReport {
+    filePath: string;
+    upsertedContracts: ContractRecord[];
+    removedSymbols: string[];
+    breakingChanges: BlastRadiusAlert[];
+    transitiveDependents: Array<{
+        filePath: string;
+        hopDistance: number;
+    }>;
+}
+declare class DependencyAndContractEngine {
+    private readonly coordDb;
+    private readonly lockEngine;
+    private readonly fencing;
+    constructor(coordDb: CoordDatabase, lockEngine: LockEngine, fencing: FencingAndAgentManager);
+    /**
+     * Scans a repository directory to index initial file dependencies and exported contracts.
+     */
+    indexRepositoryFiles(dirPath?: string): number;
+    private walkSourceFiles;
+    /**
+     * Automatically parses a modified file's imports and exports, updates the dependency graph
+     * and Contract Blackboard, and calculates the transitive blast radius
+     * if any exported signature changed or was removed.
+     */
+    recordFileModification(agentId: string | null, rawFilePath: string, sourceContent?: string): FileModificationReport;
+    /**
+     * Explicitly publishes a contract to the shared blackboard (e.g. REST route, env var, or type).
+     */
+    publishExplicitContract(params: {
+        agentId: string;
+        filePath: string;
+        symbolName: string;
+        kind: SymbolKind;
+        signature: string;
+        docComment?: string;
+    }): ContractRecord;
+    private upsertContractInternal;
+    /**
+     * Computes all files that directly or transitively import `targetFile` up to `maxHops` away.
+     */
+    getTransitiveDependents(targetFile: string, maxHops?: number): Array<{
+        filePath: string;
+        hopDistance: number;
+        importedSymbols: string[];
+    }>;
+    listContracts(filePathFilter?: string): ContractRecord[];
+    private mapRowToContract;
+}
+
+interface ConflictRecord {
+    id: string;
+    agent_a: string;
+    agent_b: string;
+    file_path: string;
+    severity: 'text_conflict' | 'transitive_contract_break';
+    details: {
+        reason: string;
+        baseBlob?: string;
+        blobA?: string;
+        blobB?: string;
+    };
+    detected_at: number;
+}
+interface DirtyMergeProbeResult {
+    clean: boolean;
+    mergedTreeSha: string | null;
+    conflicts: ConflictRecord[];
+}
+declare class ShadowGitEngine {
+    private readonly coordDb;
+    private readonly fencing;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager);
+    isGitRepository(dir?: string): boolean;
+    getHeadCommit(dir?: string): string | null;
+    private getShadowIndexPath;
+    /**
+     * Updates an agent's ephemeral shadow Git index (`.coord/shadow-index/<agent-id>.index`)
+     * without touching the repository's real `.git/index`, and creates a synthetic shadow
+     * commit object in `.git/objects` so `git merge-tree --write-tree` can run 3-way merges
+     * across uncommitted files in <15ms.
+     */
+    updateAgentShadowTree(params: {
+        agentId: string;
+        modifiedFiles?: Array<{
+            filePath: string;
+            content?: string;
+        }>;
+        worktreeDir?: string;
+    }): string | null;
+    /**
+     * Runs `git merge-tree --write-tree` across `agentId`'s dirty shadow commit and every
+     * other active agent's dirty shadow commit (or branch).
+     */
+    probeAllActiveConflicts(agentId: string, modifiedFiles?: Array<{
+        filePath: string;
+        content?: string;
+    }>, worktreeDir?: string): DirtyMergeProbeResult;
+    probePairConflict(agentA: string, commitA: string, agentB: string, commitB: string): DirtyMergeProbeResult;
+    listConflicts(): ConflictRecord[];
+}
+
+interface FileSnapshotEntry {
+    relPath: string;
+    mtimeMs: number;
+    size: number;
+    sha256: string;
+    lockedByOther: boolean;
+    backupContentBase64?: string;
+}
+interface QuarantineRecord {
+    id: string;
+    agent_id: string;
+    command: string;
+    file_path: string;
+    patch_path: string;
+    reason: string;
+    created_at: number;
+}
+interface BashGuardPostReport {
+    allowed: boolean;
+    authorizedModifiedFiles: string[];
+    quarantinedViolations: QuarantineRecord[];
+}
+declare class BashMerkleGuard {
+    private readonly coordDb;
+    private readonly fencing;
+    private readonly lockEngine;
+    private readonly depGraph;
+    private readonly shadowGit;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager, lockEngine: LockEngine, depGraph: DependencyAndContractEngine, shadowGit: ShadowGitEngine);
+    /**
+     * Checks whether a shell command is safe to execute in the workspace.
+     */
+    checkCommandSafety(params: {
+        agentId: string;
+        command: string;
+        inIsolatedWorktree?: boolean;
+    }): {
+        safe: boolean;
+        reason?: string;
+    };
+    private getSnapshotFilePath;
+    /**
+     * Captures a Merkle snapshot of workspace files before a Bash tool execution.
+     * For any file locked by another active agent, stores a full lossless backup so
+     * unauthorized mutations by bash scripts (`sed`, `python`, etc.) can be reverted atomically.
+     */
+    capturePreBashSnapshot(agentId: string, rootDir?: string): string;
+    /**
+     * Compares workspace state after a Bash command completes against the pre-Bash Merkle snapshot.
+     * Saves recovery copies of edits to files locked by sibling agents. Restoration is opt-in,
+     * and indexes authorized modifications into the AST Contract Blackboard & Dirty-Tree Conflict Radar.
+     */
+    verifyPostBashAndQuarantine(params: {
+        agentId: string;
+        command: string;
+        rootDir?: string;
+        restoreLockedFiles?: boolean;
+    }): BashGuardPostReport;
+    private quarantineAndRevertFile;
+    private walkWorkspaceFiles;
+    listQuarantined(): QuarantineRecord[];
+}
+
+interface MergeTrainEntry {
+    id: string;
+    agent_id: string;
+    branch: string;
+    worktree_path: string | null;
+    status: 'queued' | 'testing' | 'merged' | 'failed';
+    fencing_token: number;
+    verification_cmd: string | null;
+    diagnostics_output: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface SpeculativeMergeResult {
+    merged: boolean;
+    entry: MergeTrainEntry;
+    mergedCommitSha: string | null;
+    diagnostics: string;
+}
+declare class SpeculativeMergeTrain {
+    private readonly coordDb;
+    private readonly fencing;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager);
+    /**
+     * Enqueues and executes a Bors-style speculative integration test in an isolated staging
+     * worktree before advancing the main repository branch.
+     * Refuses Git conflicts and runs `verificationCmd` (e.g. `tsc --noEmit` or `npm test`) before fast-forwarding `main`.
+     */
+    enqueueAndMerge(params: {
+        agentId: string;
+        branch: string;
+        worktreePath?: string | null;
+        verificationCmd?: string | null;
+        commitMessage?: string;
+    }): SpeculativeMergeResult;
+    private gitHead;
+    private gitBranch;
+    private requireCleanTarget;
+    private cleanupStageWorktree;
+    getEntry(id: string): MergeTrainEntry | null;
+    listQueue(): MergeTrainEntry[];
+}
+
+interface ResourceRecord {
+    id: string;
+    type: 'port' | 'mutex';
+    name: string;
+    value: string;
+    owner_agent_id: string;
+    fencing_token: number;
+    queue: string[];
+    acquired_at: number;
+    expires_at: number;
+}
+declare class ResourceBroker {
+    private readonly coordDb;
+    private readonly fencing;
+    private activeExecutions;
+    hasActiveCommands(): boolean;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager);
+    /**
+     * Acquires a collision-free port lease for `(agentId, serviceName)`.
+     * Verifies both SQLite resource table and OS TCP socket availability.
+     */
+    acquirePort(params: {
+        agentId: string;
+        serviceName: string;
+        basePort?: number;
+        leaseDurationMs?: number;
+    }): Promise<{
+        port: number;
+        fencingToken: number;
+        resource: ResourceRecord;
+    }>;
+    static isTcpPortFree(port: number): Promise<boolean>;
+    /** FIFO order survives releases; queued requests belong to a specific session epoch. */
+    tryAcquireMutex(params: {
+        agentId: string;
+        mutexName: string;
+        leaseDurationMs?: number;
+        requestId?: string;
+    }): {
+        acquired: boolean;
+        fencingToken: number;
+        holderAgentId: string;
+        queuePosition: number;
+    };
+    renewMutex(params: {
+        agentId: string;
+        mutexName: string;
+        fencingToken: number;
+        leaseDurationMs?: number;
+    }): void;
+    releaseMutex(params: {
+        agentId: string;
+        mutexName: string;
+        fencingToken: number;
+    }): boolean;
+    /** Renew leases while a detached, recorded process group runs; stop it before releasing. */
+    executeWithMutex(params: {
+        agentId: string;
+        mutexName: string;
+        command: string | string[];
+        cwd?: string;
+        timeoutMs?: number;
+        commandTimeoutMs?: number;
+        leaseDurationMs?: number;
+        killGraceMs?: number;
+        signal?: AbortSignal;
+        maxOutputBytes?: number;
+        onStdout?: (chunk: Buffer) => void;
+        onStderr?: (chunk: Buffer) => void;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        waitedMs: number;
+    }>;
+    private getRun;
+    private runIsAlive;
+    private clearRun;
+    private waiters;
+    private pruneWaiters;
+    getResource(type: 'port' | 'mutex', name: string): ResourceRecord | null;
+    listResources(): ResourceRecord[];
+    private mapRow;
+}
+
+interface TaskRecord {
+    id: string;
+    title: string;
+    intent_summary: string;
+    status: 'queued' | 'active' | 'done' | 'blocked';
+    priority: number;
+    owner_agent_id: string | null;
+    fencing_token: number | null;
+    depends_on: string[];
+    scope_globs: string[];
+    created_at: number;
+    updated_at: number;
+}
+interface DeclareIntentResult {
+    ok: boolean;
+    task: TaskRecord | null;
+    fencingToken: number;
+    locks: LockRecord[];
+    lockConflicts: LockConflict[];
+    activeSiblingIntents: TaskRecord[];
+}
+declare class IntentAndTaskEngine {
+    private readonly coordDb;
+    private readonly fencing;
+    private readonly lockEngine;
+    constructor(coordDb: CoordDatabase, fencing: FencingAndAgentManager, lockEngine: LockEngine);
+    /**
+     * Peer-to-Peer Mode: Declares an agent's intent, checks scope-lock collisions
+     * and reserves the scope if available.
+     */
+    declareIntent(params: {
+        agentId: string;
+        title: string;
+        intentSummary?: string;
+        scopeGlobs: string[];
+    }): DeclareIntentResult;
+    /**
+     * Orchestrator Mode: Adds a task to the DAG queue with optional dependencies and priority.
+     */
+    addTask(params: {
+        id?: string;
+        title: string;
+        intentSummary?: string;
+        priority?: number;
+        dependsOn?: string[];
+        scopeGlobs?: string[];
+    }): TaskRecord;
+    private hasPathInDag;
+    /**
+     * Orchestrator Mode: Atomically claims the highest-priority unblocked task whose scope locks are available.
+     */
+    claimNextTask(agentId: string): {
+        claimed: boolean;
+        task: TaskRecord | null;
+        fencingToken: number | null;
+        locks: LockRecord[];
+        reason?: string;
+    };
+    completeTask(params: {
+        agentId: string;
+        taskId?: string;
+        fencingToken?: number;
+        releaseLocks?: boolean;
+    }): TaskRecord[];
+    getTask(taskId: string): TaskRecord | null;
+    listTasks(filter?: {
+        status?: TaskRecord['status'];
+    }): TaskRecord[];
+}
+
+interface AgentUnreadDelta {
+    events: CoordEvent[];
+    activeConflicts: ConflictRecord[];
+    formattedFooter: string;
+}
+interface PostFileEditHookResult {
+    filePath: string;
+    contractReport: FileModificationReport;
+    dirtyMergeConflicts: ConflictRecord[];
+    warnings: string[];
+}
+declare class KithEngine {
+    readonly coordDb: CoordDatabase;
+    readonly fencing: FencingAndAgentManager;
+    readonly locks: LockEngine;
+    readonly intents: IntentAndTaskEngine;
+    readonly depGraph: DependencyAndContractEngine;
+    readonly shadowGit: ShadowGitEngine;
+    readonly worktrees: CoWWorktreeManager;
+    readonly mergeTrain: SpeculativeMergeTrain;
+    readonly bashGuard: BashMerkleGuard;
+    readonly broker: ResourceBroker;
+    constructor(repoRoot?: string, customDbPath?: string);
+    /**
+     * Executes the complete PostToolUse pipeline whenever an agent writes or edits a file:
+     * 1. Extracts AST exports/imports and updates the Contract Blackboard & Import Graph
+     * 2. Computes transitive breaking-change blast radius across downstream dependent files
+     * 3. Updates the agent's shadow Git index (`GIT_INDEX_FILE`) and runs `git merge-tree` against sibling dirty trees
+     */
+    processPostFileEdit(params: {
+        agentId: string;
+        filePath: string;
+        content?: string;
+        worktreeDir?: string;
+    }): PostFileEditHookResult;
+    /**
+     * Consumes unread coordination events and active conflicts for `agentId` since its last tool call
+     * and formats a concise context-delta footer to append to MCP/CLI responses.
+     */
+    consumeAgentDelta(agentId: string): AgentUnreadDelta;
+    getStatus(): {
+        protocolVersion: string;
+        repository: {
+            root: string;
+            commonGitDir: string | null;
+            coordDir: string;
+        };
+        runtime: {
+            node: string;
+        };
+        fencingEpoch: number;
+        agents: AgentRecord[];
+        locks: LockRecord[];
+        tasks: TaskRecord[];
+        conflicts: ConflictRecord[];
+        contracts: ContractRecord[];
+        resources: ResourceRecord[];
+        mergeQueue: MergeTrainEntry[];
+        quarantined: QuarantineRecord[];
+        mutexWaiters: Record<string, node_sqlite.SQLOutputValue>[];
+        commandGuards: Record<string, node_sqlite.SQLOutputValue>[];
+        workspaces: WorkspaceObservation[];
+    };
+    previewIntegration(agentId: string): {
+        ok: boolean;
+        clean: null;
+        sourceHead: string;
+        targetHead: string;
+        sourceBranch: string;
+        targetBranch: string;
+        conflicts: never[];
+        dirtyFiles: WorktreeChange[];
+        targetDirtyFiles: WorktreeChange[];
+        reason: string;
+        verified?: undefined;
+    } | {
+        ok: boolean;
+        clean: boolean;
+        sourceHead: string;
+        targetHead: string;
+        sourceBranch: string;
+        targetBranch: string;
+        conflicts: string[];
+        dirtyFiles: WorktreeChange[];
+        targetDirtyFiles: WorktreeChange[];
+        verified: boolean;
+        reason?: undefined;
+    };
+    beginWork(params: Parameters<IntentAndTaskEngine['declareIntent']>[0] & {
+        isolateWorktree?: boolean;
+    }): {
+        worktree: SpawnedWorktree | null;
+        ok: boolean;
+        task: TaskRecord | null;
+        fencingToken: number;
+        locks: LockRecord[];
+        lockConflicts: LockConflict[];
+        activeSiblingIntents: TaskRecord[];
+    };
+    completeWork(params: {
+        agentId: string;
+        taskId?: string;
+        fencingToken?: number;
+        mergeBranch?: string;
+        verificationCmd?: string;
+    }): {
+        ok: boolean;
+        mergeResult: SpeculativeMergeResult;
+        error: string;
+        completedTasks?: undefined;
+    } | {
+        ok: boolean;
+        completedTasks: TaskRecord[];
+        mergeResult: SpeculativeMergeResult | null;
+        error?: undefined;
+    };
+    close(): void;
+}
+
+interface RepositoryLayout {
+    checkoutRoot: string;
+    commonGitDir: string | null;
+    isLinkedWorktree: boolean;
+    coordDir: string;
+}
+/** Resolve missing leaves through their nearest existing parent; never hide a broken link. */
+declare function physicalPath(input: string): string;
+declare function isWithin(root: string, target: string): boolean;
+/** Resolve a concrete file, including missing leaves, and refuse symlinks leaving the checkout. */
+declare function repositoryFile(root: string, file: string): string;
+/** Git's common directory identifies shared coordination; Git operations stay in this checkout. */
+declare function discoverRepository(input: string): RepositoryLayout;
+/** Read-only probe using an existing directory; uncertain results retain exclusion. */
+declare function caseSensitivePaths(root: string): boolean;
+
+/** Copies a consistent stopped-state set before opening SQLite, so even SHM reconstruction cannot touch original recovery files. */
+declare function readCoordinationState(directory?: string): {
+    protocolVersion: string;
+    observedAt: number;
+    repository: {
+        root: string;
+        commonGitDir: string | null;
+        coordDir: string;
+    };
+    runtime: {
+        node: string;
+    };
+    state: "ready" | "missing" | "unavailable";
+    error: string | undefined;
+    fencingEpoch: number;
+    agents: AgentRecord[];
+    tasks: Record<string, unknown>[];
+    locks: Record<string, unknown>[];
+    conflicts: Record<string, unknown>[];
+    contracts: Record<string, unknown>[];
+    resources: Record<string, unknown>[];
+    mergeQueue: Record<string, unknown>[];
+    quarantined: Record<string, unknown>[];
+    mutexWaiters: Record<string, unknown>[];
+    commandGuards: Record<string, unknown>[];
+    events: Record<string, unknown>[];
+    workspaces: ReturnType<typeof observeWorkspaces>;
+} | {
+    state: "ready";
+    fencingEpoch: number;
+    agents: AgentRecord[];
+    tasks: {
+        depends_on: any;
+        scope_globs: any;
+    }[];
+    locks: Record<string, unknown>[];
+    conflicts: {
+        details: any;
+    }[];
+    contracts: {
+        is_breaking: boolean;
+    }[];
+    resources: Record<string, unknown>[];
+    mergeQueue: Record<string, unknown>[];
+    quarantined: Record<string, unknown>[];
+    mutexWaiters: Record<string, unknown>[];
+    commandGuards: Record<string, unknown>[];
+    events: {
+        payload: any;
+    }[];
+    workspaces: WorkspaceObservation[];
+    protocolVersion: string;
+    observedAt: number;
+    repository: {
+        root: string;
+        commonGitDir: string | null;
+        coordDir: string;
+    };
+    runtime: {
+        node: string;
+    };
+    error: string | undefined;
+};
+/** Recovery is an inspection report: it never clears guards, expires claims, deletes worktrees or restores files. */
+declare function recoveryReport(directory?: string): {
+    retainedWorktrees: {
+        path: string;
+        symlink: boolean;
+        agentIds: string[];
+    }[];
+    expiredClaims: Record<string, unknown>[];
+    unfinishedIntegrations: Record<string, unknown>[];
+    setupLock: {
+        path: string;
+        present: boolean;
+    };
+    integrationLock: {
+        path: string;
+        present: boolean;
+    };
+    protocolVersion: string;
+    observedAt: number;
+    repository: {
+        root: string;
+        commonGitDir: string | null;
+        coordDir: string;
+    };
+    runtime: {
+        node: string;
+    };
+    state: "ready" | "missing" | "unavailable";
+    error: string | undefined;
+    fencingEpoch: number;
+    agents: AgentRecord[];
+    tasks: Record<string, unknown>[];
+    locks: Record<string, unknown>[];
+    conflicts: Record<string, unknown>[];
+    contracts: Record<string, unknown>[];
+    resources: Record<string, unknown>[];
+    mergeQueue: Record<string, unknown>[];
+    quarantined: Record<string, unknown>[];
+    mutexWaiters: Record<string, unknown>[];
+    commandGuards: Record<string, unknown>[];
+    events: Record<string, unknown>[];
+    workspaces: ReturnType<typeof observeWorkspaces>;
+} | {
+    retainedWorktrees: {
+        path: string;
+        symlink: boolean;
+        agentIds: string[];
+    }[];
+    expiredClaims: Record<string, unknown>[];
+    unfinishedIntegrations: Record<string, unknown>[];
+    setupLock: {
+        path: string;
+        present: boolean;
+    };
+    integrationLock: {
+        path: string;
+        present: boolean;
+    };
+    state: "ready";
+    fencingEpoch: number;
+    agents: AgentRecord[];
+    tasks: {
+        depends_on: any;
+        scope_globs: any;
+    }[];
+    locks: Record<string, unknown>[];
+    conflicts: {
+        details: any;
+    }[];
+    contracts: {
+        is_breaking: boolean;
+    }[];
+    resources: Record<string, unknown>[];
+    mergeQueue: Record<string, unknown>[];
+    quarantined: Record<string, unknown>[];
+    mutexWaiters: Record<string, unknown>[];
+    commandGuards: Record<string, unknown>[];
+    events: {
+        payload: any;
+    }[];
+    workspaces: WorkspaceObservation[];
+    protocolVersion: string;
+    observedAt: number;
+    repository: {
+        root: string;
+        commonGitDir: string | null;
+        coordDir: string;
+    };
+    runtime: {
+        node: string;
+    };
+    error: string | undefined;
+};
+
+declare const KITH_VERSION = "0.1.0";
+declare const KITH_PROTOCOL_VERSION = "1.0.0";
+
+export { type AcquireLockResult, type AgentRecord, type AgentUnreadDelta, AstAnalyzer, type BashGuardPostReport, BashMerkleGuard, type BlastRadiusAlert, CoWWorktreeManager, type ConflictRecord, type ContractRecord, CoordDatabase, type CoordEvent, type DeclareIntentResult, DependencyAndContractEngine, type DirtyMergeProbeResult, type ExtractedImport, type ExtractedSymbol, FencingAndAgentManager, type FileAstAnalysis, type FileModificationReport, type FileSnapshotEntry, IntentAndTaskEngine, KITH_PROTOCOL_VERSION, KITH_VERSION, KithEngine, type LockConflict, LockEngine, type LockRecord, type MergeTrainEntry, type PostFileEditHookResult, type QuarantineRecord, type RepositoryLayout, ResourceBroker, type ResourceRecord, SessionOwnershipError, type SessionRegistration, ShadowGitEngine, type SpawnedWorktree, type SpeculativeMergeResult, SpeculativeMergeTrain, StaleFencingTokenError, type SymbolKind, type TaskRecord, type WorkspaceObservation, type WorktreeChange, caseSensitivePaths, discoverRepository, isWithin, observeWorkspaces, physicalPath, previewIntegration, readCoordinationState, recoveryReport, repositoryFile, worktreeChanges };