talking-stick 0.1.0-alpha

package/dist/service.js

@@ -0,0 +1,980 @@
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import { setTimeout as sleep } from "node:timers/promises";
+import { ancestorPaths, resolveContextPath } from "./path-resolution.js";
+import { defaultPolicy } from "./config.js";
+import { openDatabase, withImmediateTransaction } from "./db.js";
+import { ProtocolError } from "./errors.js";
+import { createSystemProcessInspector } from "./process-utils.js";
+export class TalkingStickService {
+    db;
+    policy;
+    now;
+    ownsDatabase;
+    processLivenessChecker;
+    hostId;
+    constructor(options = {}) {
+        this.db = options.db ?? openDatabase(options);
+        this.ownsDatabase = !options.db;
+        this.now = options.now ?? (() => new Date());
+        this.policy = { ...defaultPolicy, ...options.policy };
+        this.hostId = options.hostId ?? os.hostname();
+        this.processLivenessChecker =
+            options.processLivenessChecker ??
+                createDefaultProcessLivenessChecker(this.hostId);
+    }
+    close() {
+        if (this.ownsDatabase && this.db.open) {
+            this.db.close();
+        }
+    }
+    listRooms(input = {}) {
+        const now = this.now();
+        if (!input.context_path) {
+            const rows = this.db
+                .prepare("SELECT * FROM path_rooms ORDER BY canonical_path")
+                .all();
+            return {
+                rooms: rows.map((row) => this.mapRoomForList(row, now))
+            };
+        }
+        const resolved = resolveContextPath(input.context_path);
+        const ancestors = ancestorPaths(resolved.canonical_context_path, resolved.workspace_root);
+        return {
+            rooms: this.findRoomsByCanonicalPaths(ancestors).map((row) => this.mapRoomForList(row, now))
+        };
+    }
+    joinPath(input) {
+        assertNonEmpty(input.agent_id, "agent_id");
+        assertNonEmpty(input.context_path, "context_path");
+        const resolved = resolveContextPath(input.context_path);
+        const now = this.now();
+        const timestamp = now.toISOString();
+        return withImmediateTransaction(this.db, () => {
+            const roomSelection = this.findOrCreateRoomForJoin(resolved, input.force_new === true, timestamp);
+            this.upsertMember(roomSelection.room.room_id, input.agent_id, timestamp, input.process_metadata);
+            const freshRoom = this.requireRoom(roomSelection.room.room_id);
+            return {
+                agent_id: input.agent_id,
+                room_id: freshRoom.room_id,
+                canonical_path: freshRoom.canonical_path,
+                requested_path: resolved.requested_path,
+                workspace_root: resolved.workspace_root,
+                joined_existing_room: roomSelection.joinedExistingRoom,
+                warning: roomSelection.warning,
+                policy: { ...this.policy },
+                room_state: this.mapRoom(this.inspectRoom(freshRoom, now), now),
+                handoff_template: handoffTemplate()
+            };
+        });
+    }
+    async waitForTurn(input) {
+        assertNonEmpty(input.agent_id, "agent_id");
+        assertNonEmpty(input.room_id, "room_id");
+        const maxWaitMs = input.max_wait_ms ?? this.policy.waitForTurnMaxWaitMs;
+        const deadline = Date.now() + Math.max(0, maxWaitMs);
+        while (true) {
+            this.warmRoomTurnLiveness(input.room_id);
+            const result = withImmediateTransaction(this.db, () => this.waitForTurnOnce(input));
+            if (result.status !== "not_yet" || Date.now() >= deadline) {
+                return result;
+            }
+            const remainingMs = deadline - Date.now();
+            await sleep(Math.min(this.policy.waitForTurnPollMs, remainingMs));
+        }
+    }
+    heartbeat(input) {
+        const now = this.now();
+        const timestamp = now.toISOString();
+        const nextLeaseExpiresAt = this.expiresAt(now, this.policy.ownerLeaseTtlMs);
+        this.warmRoomTurnLiveness(input.room_id);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            this.assertOwnerMutation(room, input, now);
+            this.touchMember(input.room_id, input.agent_id, timestamp);
+            this.db
+                .prepare(`
+          UPDATE path_rooms
+          SET lease_expires_at = ?, updated_at = ?, state = 'owned'
+          WHERE room_id = ?
+        `)
+                .run(nextLeaseExpiresAt, timestamp, input.room_id);
+            return {
+                status: "ok",
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                lease_id: input.lease_id,
+                lease_expires_at: nextLeaseExpiresAt
+            };
+        });
+    }
+    releaseStick(input) {
+        validateHandoff(input.handoff);
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.warmRoomTurnLiveness(input.room_id);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            this.assertOwnerMutation(room, input, now);
+            this.touchMember(input.room_id, input.agent_id, timestamp);
+            const eventSeq = this.appendEvent({
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                event_type: "release",
+                from_agent_id: input.agent_id,
+                to_agent_id: null,
+                handoff: input.handoff,
+                reason: null,
+                created_at: timestamp
+            });
+            const nextMember = this.findNextActiveMember(input.room_id, input.agent_id, now);
+            const reservedFor = nextMember?.agent_id ?? null;
+            const claimExpiresAt = reservedFor
+                ? this.expiresAt(now, this.policy.claimTtlMs)
+                : null;
+            this.db
+                .prepare(`
+          UPDATE path_rooms
+          SET sequence_index = ?,
+              owner = NULL,
+              reserved_for = ?,
+              pending_handoff_event_seq = ?,
+              lease_id = NULL,
+              lease_expires_at = NULL,
+              claim_expires_at = ?,
+              state = ?,
+              updated_at = ?
+          WHERE room_id = ?
+        `)
+                .run(nextMember?.ordinal ?? room.sequence_index, reservedFor, eventSeq, claimExpiresAt, reservedFor ? "reserved" : "idle", timestamp, input.room_id);
+            return {
+                status: "released",
+                room_id: input.room_id,
+                reserved_for: reservedFor,
+                event_seq: eventSeq
+            };
+        });
+    }
+    passStick(input) {
+        validateHandoff(input.handoff);
+        assertNonEmpty(input.to_agent_id, "to_agent_id");
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.warmRoomTurnLiveness(input.room_id);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            this.assertOwnerMutation(room, input, now);
+            this.touchMember(input.room_id, input.agent_id, timestamp);
+            const target = this.getMember(input.room_id, input.to_agent_id);
+            if (!target || !this.isMemberActive(target, now)) {
+                throw new ProtocolError("unknown_member", "pass_stick target must be an active room member in the MVP.", { to_agent_id: input.to_agent_id });
+            }
+            const eventSeq = this.appendEvent({
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                event_type: "pass",
+                from_agent_id: input.agent_id,
+                to_agent_id: input.to_agent_id,
+                handoff: input.handoff,
+                reason: null,
+                created_at: timestamp
+            });
+            this.db
+                .prepare(`
+          UPDATE path_rooms
+          SET sequence_index = ?,
+              owner = NULL,
+              reserved_for = ?,
+              pending_handoff_event_seq = ?,
+              lease_id = NULL,
+              lease_expires_at = NULL,
+              claim_expires_at = ?,
+              state = 'reserved',
+              updated_at = ?
+          WHERE room_id = ?
+        `)
+                .run(target.ordinal, input.to_agent_id, eventSeq, this.expiresAt(now, this.policy.claimTtlMs), timestamp, input.room_id);
+            return {
+                status: "passed",
+                room_id: input.room_id,
+                reserved_for: input.to_agent_id,
+                event_seq: eventSeq
+            };
+        });
+    }
+    takeoverStick(input) {
+        assertNonEmpty(input.agent_id, "agent_id");
+        assertNonEmpty(input.room_id, "room_id");
+        assertNonEmpty(input.reason, "reason");
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.warmRoomTurnLiveness(input.room_id);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            const inspection = this.inspectRoomForMutation(room, now);
+            if (room.turn_id !== input.expected_turn_id) {
+                throw new ProtocolError("turn_mismatch", "The supplied turn does not match the current room turn.", {
+                    current_owner: room.owner,
+                    current_turn_id: room.turn_id,
+                    room_state: inspection.state
+                });
+            }
+            this.touchMember(input.room_id, input.agent_id, timestamp);
+            const takeoverKind = this.assertTakeoverEligible(room, input.agent_id, now, inspection);
+            const nextTurnId = room.turn_id + 1;
+            const leaseId = randomUUID();
+            const revokedAgentId = takeoverKind === "claim_timeout" || takeoverKind === "recipient_gone"
+                ? room.reserved_for
+                : room.owner;
+            this.db
+                .prepare(`
+          UPDATE path_rooms
+          SET owner = ?,
+              reserved_for = NULL,
+              pending_handoff_event_seq = NULL,
+              turn_id = ?,
+              lease_id = ?,
+              lease_expires_at = ?,
+              claim_expires_at = NULL,
+              state = 'owned',
+              updated_at = ?
+          WHERE room_id = ?
+        `)
+                .run(input.agent_id, nextTurnId, leaseId, this.expiresAt(now, this.policy.ownerLeaseTtlMs), timestamp, input.room_id);
+            this.appendEvent({
+                room_id: input.room_id,
+                turn_id: nextTurnId,
+                event_type: "takeover",
+                from_agent_id: revokedAgentId,
+                to_agent_id: input.agent_id,
+                handoff: null,
+                reason: input.reason,
+                created_at: timestamp
+            });
+            return {
+                status: "your_turn",
+                room_id: input.room_id,
+                turn_id: nextTurnId,
+                lease_id: leaseId,
+                revoked_agent_id: revokedAgentId,
+                reason: takeoverKind
+            };
+        });
+    }
+    getRoomState(input) {
+        const now = this.now();
+        const room = this.requireRoom(input.room_id);
+        const inspection = this.inspectRoom(room, now);
+        return {
+            room: this.mapRoom(inspection, now),
+            members: inspection.members.map((member) => this.mapMember(member, now))
+        };
+    }
+    getRoomEvents(input) {
+        const afterEventSeq = input.after_event_seq ?? 0;
+        const limit = Math.min(input.limit ?? 100, 500);
+        return this.db
+            .prepare(`
+        SELECT *
+        FROM room_events
+        WHERE room_id = ? AND event_seq > ?
+        ORDER BY event_seq
+        LIMIT ?
+      `)
+            .all(input.room_id, afterEventSeq, limit)
+            .map((row) => this.mapEvent(row));
+    }
+    waitForTurnOnce(input) {
+        const now = this.now();
+        const timestamp = now.toISOString();
+        const room = this.requireRoom(input.room_id);
+        this.touchMember(input.room_id, input.agent_id, timestamp);
+        const inspection = this.inspectRoomForMutation(room, now);
+        if (room.state === "closed") {
+            return { status: "closed", room_id: input.room_id };
+        }
+        if (!room.owner && !room.reserved_for) {
+            return this.grantTurn(room, input.agent_id, now);
+        }
+        if (inspection.state === "recipient_gone") {
+            if (room.reserved_for !== input.agent_id &&
+                this.isClaimTakeoverEligible(room, input.agent_id, now, inspection)) {
+                return {
+                    status: "takeover_available",
+                    room_id: input.room_id,
+                    turn_id: room.turn_id,
+                    room_state: "recipient_gone",
+                    reason: "recipient_gone",
+                    reserved_for: room.reserved_for ?? undefined
+                };
+            }
+        }
+        if (room.reserved_for) {
+            if (room.reserved_for === input.agent_id &&
+                inspection.state !== "recipient_gone") {
+                return this.grantTurn(room, input.agent_id, now);
+            }
+            if (inspection.state !== "recipient_gone" &&
+                this.hasExpired(room.claim_expires_at, now) &&
+                this.isClaimTakeoverEligible(room, input.agent_id, now, inspection)) {
+                return {
+                    status: "takeover_available",
+                    room_id: input.room_id,
+                    turn_id: room.turn_id,
+                    room_state: "reserved",
+                    reason: "claim_timeout",
+                    reserved_for: room.reserved_for
+                };
+            }
+        }
+        if (inspection.state === "owner_gone" && room.owner !== input.agent_id) {
+            return {
+                status: "takeover_available",
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                room_state: "owner_gone",
+                reason: "owner_gone",
+                current_owner: room.owner ?? undefined
+            };
+        }
+        if (room.owner && room.owner !== input.agent_id && inspection.state === "stale_owner") {
+            return {
+                status: "takeover_available",
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                room_state: "stale_owner",
+                reason: "owner_timeout",
+                current_owner: room.owner
+            };
+        }
+        return {
+            status: "not_yet",
+            cursor: String(this.latestEventSeq(input.room_id)),
+            room_state: inspection.state
+        };
+    }
+    grantTurn(room, agentId, now) {
+        const timestamp = now.toISOString();
+        const nextTurnId = room.turn_id + 1;
+        const leaseId = randomUUID();
+        const pendingEvent = room.pending_handoff_event_seq
+            ? this.getEventBySeq(room.pending_handoff_event_seq)
+            : null;
+        const reason = claimReasonForEvent(pendingEvent);
+        this.db
+            .prepare(`
+        UPDATE path_rooms
+        SET owner = ?,
+            reserved_for = NULL,
+            pending_handoff_event_seq = NULL,
+            turn_id = ?,
+            lease_id = ?,
+            lease_expires_at = ?,
+            claim_expires_at = NULL,
+            state = 'owned',
+            updated_at = ?
+        WHERE room_id = ?
+      `)
+            .run(agentId, nextTurnId, leaseId, this.expiresAt(now, this.policy.ownerLeaseTtlMs), timestamp, room.room_id);
+        this.appendEvent({
+            room_id: room.room_id,
+            turn_id: nextTurnId,
+            event_type: "claim",
+            from_agent_id: pendingEvent?.from_agent_id ?? null,
+            to_agent_id: agentId,
+            handoff: null,
+            reason: null,
+            created_at: timestamp
+        });
+        return {
+            status: "your_turn",
+            room_id: room.room_id,
+            turn_id: nextTurnId,
+            lease_id: leaseId,
+            handoff: pendingEvent ? this.mapEvent(pendingEvent).handoff : null,
+            from_agent_id: pendingEvent?.from_agent_id ?? null,
+            reason
+        };
+    }
+    findOrCreateRoomForJoin(resolved, forceNew, timestamp) {
+        const ancestors = ancestorPaths(resolved.canonical_context_path, resolved.workspace_root);
+        const existingAncestor = this.findDeepestRoom(ancestors);
+        if (forceNew) {
+            const exactRoom = this.findRoomByCanonicalPath(resolved.canonical_context_path);
+            if (exactRoom) {
+                return { room: exactRoom, joinedExistingRoom: true };
+            }
+            return {
+                room: this.createRoom(resolved.canonical_context_path, timestamp),
+                joinedExistingRoom: false,
+                warning: existingAncestor
+                    ? `Created nested room inside ${existingAncestor.canonical_path}`
+                    : undefined
+            };
+        }
+        if (existingAncestor) {
+            return { room: existingAncestor, joinedExistingRoom: true };
+        }
+        return {
+            room: this.createRoom(resolved.workspace_root, timestamp),
+            joinedExistingRoom: false
+        };
+    }
+    createRoom(canonicalPath, timestamp) {
+        const roomId = randomUUID();
+        this.db
+            .prepare(`
+        INSERT INTO path_rooms (
+          room_id,
+          canonical_path,
+          sequence_index,
+          owner,
+          reserved_for,
+          pending_handoff_event_seq,
+          turn_id,
+          lease_id,
+          lease_expires_at,
+          claim_expires_at,
+          state,
+          updated_at
+        )
+        VALUES (?, ?, 0, NULL, NULL, NULL, 0, NULL, NULL, NULL, 'idle', ?)
+      `)
+            .run(roomId, canonicalPath, timestamp);
+        return this.requireRoom(roomId);
+    }
+    upsertMember(roomId, agentId, timestamp, processMetadata) {
+        const existing = this.getMember(roomId, agentId);
+        const normalizedMetadata = normalizeProcessMetadata(processMetadata);
+        if (existing) {
+            const room = this.requireRoom(roomId);
+            const mergedMetadata = this.mergeMemberProcessMetadata(room, existing, normalizedMetadata);
+            this.db
+                .prepare(`
+          UPDATE room_members
+          SET last_seen_at = ?,
+              status = 'active',
+              host_id = ?,
+              pid = ?,
+              process_started_at = ?,
+              session_kind = ?,
+              display_name = ?
+          WHERE room_id = ? AND agent_id = ?
+        `)
+                .run(timestamp, mergedMetadata.host_id, mergedMetadata.pid, mergedMetadata.process_started_at, mergedMetadata.session_kind, mergedMetadata.display_name, roomId, agentId);
+            return;
+        }
+        const nextOrdinal = this.db
+            .prepare("SELECT MAX(ordinal) + 1 AS next_ordinal FROM room_members WHERE room_id = ?")
+            .get(roomId)?.next_ordinal ?? 0;
+        this.db
+            .prepare(`
+        INSERT INTO room_members (
+          room_id,
+          agent_id,
+          ordinal,
+          joined_at,
+          last_seen_at,
+          status,
+          host_id,
+          pid,
+          process_started_at,
+          session_kind,
+          display_name
+        )
+        VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)
+      `)
+            .run(roomId, agentId, nextOrdinal, timestamp, timestamp, normalizedMetadata.host_id, normalizedMetadata.pid, normalizedMetadata.process_started_at, normalizedMetadata.session_kind, normalizedMetadata.display_name);
+    }
+    mergeMemberProcessMetadata(room, existing, incoming) {
+        if (!this.shouldPreserveExactMemberProcessMetadata(room, existing, incoming)) {
+            return incoming;
+        }
+        return {
+            host_id: existing.host_id,
+            pid: existing.pid,
+            process_started_at: existing.process_started_at,
+            session_kind: existing.session_kind,
+            display_name: existing.display_name
+        };
+    }
+    shouldPreserveExactMemberProcessMetadata(room, existing, incoming) {
+        const isCurrentHolderOrRecipient = room.owner === existing.agent_id || room.reserved_for === existing.agent_id;
+        if (!isCurrentHolderOrRecipient) {
+            return false;
+        }
+        if (!hasExactProcessIdentity(existing)) {
+            return false;
+        }
+        if (!hasExactProcessIdentity(incoming)) {
+            return true;
+        }
+        return (sessionKindPriority(incoming.session_kind) <
+            sessionKindPriority(existing.session_kind));
+    }
+    touchMember(roomId, agentId, timestamp) {
+        const result = this.db
+            .prepare(`
+        UPDATE room_members
+        SET last_seen_at = ?, status = 'active'
+        WHERE room_id = ? AND agent_id = ?
+      `)
+            .run(timestamp, roomId, agentId);
+        if (result.changes === 0) {
+            throw new ProtocolError("unknown_member", "Agent must join the room before using this tool.", { to_agent_id: agentId });
+        }
+    }
+    assertOwnerMutation(room, input, now) {
+        const inspection = this.inspectRoomForMutation(room, now);
+        if (room.turn_id !== input.expected_turn_id) {
+            throw new ProtocolError("turn_mismatch", "The supplied turn does not match the current room turn.", {
+                current_owner: room.owner,
+                current_turn_id: room.turn_id,
+                room_state: inspection.state
+            });
+        }
+        if (room.owner !== input.agent_id ||
+            room.lease_id !== input.lease_id ||
+            room.state !== "owned" ||
+            (inspection.state !== "owned" && inspection.state !== "stale_owner")) {
+            throw new ProtocolError("stale_lease", "The supplied lease is no longer current for this room.", {
+                current_owner: room.owner,
+                current_turn_id: room.turn_id,
+                room_state: inspection.state
+            });
+        }
+    }
+    assertTakeoverEligible(room, agentId, now, inspection) {
+        if (inspection.state === "recipient_gone") {
+            if (!this.isClaimTakeoverEligible(room, agentId, now, inspection)) {
+                throw new ProtocolError("takeover_ineligible", "Agent is not eligible to take over this reserved turn.", {
+                    reserved_for: room.reserved_for,
+                    room_state: inspection.state
+                });
+            }
+            return "recipient_gone";
+        }
+        if (room.reserved_for && this.hasExpired(room.claim_expires_at, now)) {
+            if (!this.isClaimTakeoverEligible(room, agentId, now, inspection)) {
+                throw new ProtocolError("takeover_ineligible", "Agent is not eligible to take over this reserved turn.", {
+                    reserved_for: room.reserved_for,
+                    room_state: inspection.state
+                });
+            }
+            return "claim_timeout";
+        }
+        if (inspection.state === "owner_gone" && room.owner) {
+            if (room.owner === agentId) {
+                throw new ProtocolError("takeover_ineligible", "The current owner cannot take over its own dead lease.", {
+                    current_owner: room.owner,
+                    room_state: inspection.state
+                });
+            }
+            return "owner_gone";
+        }
+        if (room.owner && this.hasExpired(room.lease_expires_at, now)) {
+            if (room.owner === agentId) {
+                throw new ProtocolError("takeover_ineligible", "The current owner cannot take over its own stale lease.", {
+                    current_owner: room.owner,
+                    room_state: inspection.state
+                });
+            }
+            return "owner_timeout";
+        }
+        throw new ProtocolError("takeover_not_available", "No takeover timeout is currently available for this room.", { room_state: inspection.state });
+    }
+    isClaimTakeoverEligible(room, agentId, now, inspection) {
+        if (!room.reserved_for || room.reserved_for === agentId) {
+            return false;
+        }
+        const pendingEvent = room.pending_handoff_event_seq
+            ? this.getEventBySeq(room.pending_handoff_event_seq)
+            : null;
+        const priorOwner = pendingEvent?.from_agent_id ?? null;
+        if (priorOwner === agentId) {
+            return !this.hasOtherClaimTakeoverCandidate(inspection.members, room.reserved_for, agentId, now);
+        }
+        return true;
+    }
+    hasOtherClaimTakeoverCandidate(members, reservedFor, candidateAgentId, now) {
+        return members.some((member) => member.agent_id !== candidateAgentId &&
+            member.agent_id !== reservedFor &&
+            this.hasRecentPresence(member, now));
+    }
+    findNextActiveMember(roomId, afterAgentId, now) {
+        const members = this.getMembers(roomId);
+        if (members.length <= 1) {
+            return null;
+        }
+        const ownerIndex = members.findIndex((member) => member.agent_id === afterAgentId);
+        if (ownerIndex === -1) {
+            return null;
+        }
+        for (let offset = 1; offset < members.length; offset += 1) {
+            const candidate = members[(ownerIndex + offset) % members.length];
+            if (this.hasRecentPresence(candidate, now)) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    appendEvent(input) {
+        const result = this.db
+            .prepare(`
+        INSERT INTO room_events (
+          event_id,
+          room_id,
+          turn_id,
+          event_type,
+          from_agent_id,
+          to_agent_id,
+          handoff_json,
+          reason,
+          created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+            .run(randomUUID(), input.room_id, input.turn_id, input.event_type, input.from_agent_id, input.to_agent_id, input.handoff ? JSON.stringify(input.handoff) : null, input.reason, input.created_at);
+        return Number(result.lastInsertRowid);
+    }
+    getRoomRow(roomId) {
+        return this.db
+            .prepare("SELECT * FROM path_rooms WHERE room_id = ?")
+            .get(roomId);
+    }
+    requireRoom(roomId) {
+        const room = this.getRoomRow(roomId);
+        if (!room) {
+            throw new ProtocolError("room_not_found", "Room was not found.");
+        }
+        return room;
+    }
+    findRoomByCanonicalPath(canonicalPath) {
+        return (this.db
+            .prepare("SELECT * FROM path_rooms WHERE canonical_path = ?")
+            .get(canonicalPath) ?? null);
+    }
+    findRoomsByCanonicalPaths(canonicalPaths) {
+        if (canonicalPaths.length === 0) {
+            return [];
+        }
+        const placeholders = canonicalPaths.map(() => "?").join(", ");
+        return this.db
+            .prepare(`SELECT * FROM path_rooms WHERE canonical_path IN (${placeholders})`)
+            .all(...canonicalPaths);
+    }
+    findDeepestRoom(canonicalPaths) {
+        const rows = this.findRoomsByCanonicalPaths(canonicalPaths);
+        const byPath = new Map(rows.map((row) => [row.canonical_path, row]));
+        for (const candidate of canonicalPaths) {
+            const row = byPath.get(candidate);
+            if (row) {
+                return row;
+            }
+        }
+        return null;
+    }
+    getMember(roomId, agentId) {
+        return (this.db
+            .prepare("SELECT * FROM room_members WHERE room_id = ? AND agent_id = ?")
+            .get(roomId, agentId) ?? null);
+    }
+    getMembers(roomId) {
+        return this.db
+            .prepare("SELECT * FROM room_members WHERE room_id = ? ORDER BY ordinal")
+            .all(roomId);
+    }
+    getEventBySeq(eventSeq) {
+        return (this.db
+            .prepare("SELECT * FROM room_events WHERE event_seq = ?")
+            .get(eventSeq) ?? null);
+    }
+    latestEventSeq(roomId) {
+        return (this.db
+            .prepare("SELECT MAX(event_seq) AS event_seq FROM room_events WHERE room_id = ?")
+            .get(roomId)?.event_seq ?? 0);
+    }
+    expiresAt(now, ttlMs) {
+        return new Date(now.getTime() + ttlMs).toISOString();
+    }
+    hasExpired(timestamp, now) {
+        return timestamp !== null && Date.parse(timestamp) <= now.getTime();
+    }
+    isMemberActive(member, now) {
+        if (this.getMemberProcessLiveness(member) === "gone") {
+            return false;
+        }
+        return this.hasRecentPresence(member, now);
+    }
+    hasRecentPresence(member, now) {
+        return (now.getTime() - Date.parse(member.last_seen_at) <=
+            this.policy.presenceTtlMs);
+    }
+    inspectRoom(room, now) {
+        const members = this.getMembers(room.room_id);
+        const ownerMember = room.owner
+            ? members.find((member) => member.agent_id === room.owner) ?? null
+            : null;
+        const reservedMember = room.reserved_for
+            ? members.find((member) => member.agent_id === room.reserved_for) ?? null
+            : null;
+        let state;
+        if (room.state === "closed") {
+            state = "closed";
+        }
+        else if (room.owner) {
+            const ownerLiveness = ownerMember
+                ? this.getMemberProcessLiveness(ownerMember)
+                : "gone";
+            if (ownerLiveness === "gone") {
+                state = "owner_gone";
+            }
+            else if (this.hasExpired(room.lease_expires_at, now)) {
+                state = "stale_owner";
+            }
+            else {
+                state = "owned";
+            }
+        }
+        else if (room.reserved_for) {
+            const reservedLiveness = reservedMember
+                ? this.getMemberProcessLiveness(reservedMember)
+                : "gone";
+            state = reservedLiveness === "gone" ? "recipient_gone" : "reserved";
+        }
+        else if (!members.some((member) => this.isMemberActive(member, now))) {
+            state = "dormant";
+        }
+        else {
+            state = "idle";
+        }
+        return {
+            room,
+            members,
+            ownerMember,
+            reservedMember,
+            state
+        };
+    }
+    inspectRoomForMutation(room, now) {
+        const members = this.getMembers(room.room_id);
+        const ownerMember = room.owner
+            ? members.find((member) => member.agent_id === room.owner) ?? null
+            : null;
+        const reservedMember = room.reserved_for
+            ? members.find((member) => member.agent_id === room.reserved_for) ?? null
+            : null;
+        let state;
+        if (room.state === "closed") {
+            state = "closed";
+        }
+        else if (room.owner) {
+            const ownerLiveness = ownerMember
+                ? this.getMemberProcessLiveness(ownerMember)
+                : "gone";
+            if (ownerLiveness === "gone") {
+                state = "owner_gone";
+            }
+            else if (this.hasExpired(room.lease_expires_at, now)) {
+                state = "stale_owner";
+            }
+            else {
+                state = "owned";
+            }
+        }
+        else if (room.reserved_for) {
+            const reservedLiveness = reservedMember
+                ? this.getMemberProcessLiveness(reservedMember)
+                : "gone";
+            state = reservedLiveness === "gone" ? "recipient_gone" : "reserved";
+        }
+        else if (!members.some((member) => this.hasRecentPresence(member, now))) {
+            state = "dormant";
+        }
+        else {
+            state = "idle";
+        }
+        return {
+            room,
+            members,
+            ownerMember,
+            reservedMember,
+            state
+        };
+    }
+    mapRoomForList(room, now) {
+        let state;
+        if (room.state === "closed") {
+            state = "closed";
+        }
+        else if (room.owner) {
+            state = this.hasExpired(room.lease_expires_at, now)
+                ? "stale_owner"
+                : "owned";
+        }
+        else if (room.reserved_for) {
+            state = "reserved";
+        }
+        else {
+            const members = this.getMembers(room.room_id);
+            state = members.some((member) => this.hasRecentPresence(member, now))
+                ? "idle"
+                : "dormant";
+        }
+        return {
+            ...room,
+            state
+        };
+    }
+    warmRoomTurnLiveness(roomId) {
+        const room = this.getRoomRow(roomId);
+        if (!room) {
+            return;
+        }
+        const members = this.getMembers(roomId);
+        if (room.owner) {
+            const owner = members.find((member) => member.agent_id === room.owner);
+            if (owner) {
+                this.getMemberProcessLiveness(owner);
+            }
+            return;
+        }
+        if (room.reserved_for) {
+            const reserved = members.find((member) => member.agent_id === room.reserved_for);
+            if (reserved) {
+                this.getMemberProcessLiveness(reserved);
+            }
+        }
+    }
+    getMemberProcessLiveness(member) {
+        return this.processLivenessChecker({
+            host_id: member.host_id,
+            pid: member.pid,
+            process_started_at: member.process_started_at,
+            session_kind: member.session_kind,
+            display_name: member.display_name
+        });
+    }
+    deriveRoomState(room, now) {
+        return this.inspectRoom(room, now).state;
+    }
+    mapRoom(inspection, now) {
+        const row = inspection.room;
+        return {
+            ...row,
+            state: inspection.state
+        };
+    }
+    mapMember(row, now) {
+        return {
+            ...row,
+            status: this.isMemberActive(row, now) ? "active" : "inactive"
+        };
+    }
+    mapEvent(row) {
+        return {
+            event_seq: row.event_seq,
+            event_id: row.event_id,
+            room_id: row.room_id,
+            turn_id: row.turn_id,
+            event_type: row.event_type,
+            from_agent_id: row.from_agent_id,
+            to_agent_id: row.to_agent_id,
+            handoff: row.handoff_json
+                ? JSON.parse(row.handoff_json)
+                : null,
+            reason: row.reason,
+            created_at: row.created_at
+        };
+    }
+}
+function normalizeProcessMetadata(processMetadata) {
+    return {
+        host_id: processMetadata?.host_id ?? null,
+        pid: processMetadata?.pid ?? null,
+        process_started_at: processMetadata?.process_started_at ?? null,
+        session_kind: processMetadata?.session_kind ?? "mcp_harness",
+        display_name: processMetadata?.display_name ?? null
+    };
+}
+function createDefaultProcessLivenessChecker(currentHostId) {
+    // This cache keeps normal polling from forking `ps` on every room inspection.
+    // A deeper move to out-of-transaction liveness refresh is possible later, but
+    // for the MVP we keep the lock boundary simple and the probe shared/cached.
+    const inspector = createSystemProcessInspector({ cacheTtlMs: 1_000 });
+    return (metadata) => {
+        if (metadata.pid === null ||
+            metadata.process_started_at === null ||
+            metadata.process_started_at.trim() === "") {
+            return "unknown";
+        }
+        if (metadata.host_id && metadata.host_id !== currentHostId) {
+            return "unknown";
+        }
+        if (process.platform === "win32") {
+            return "unknown";
+        }
+        const inspection = inspector.inspect(metadata.pid);
+        if (inspection === undefined) {
+            return "unknown";
+        }
+        if (inspection === null || !inspection.startTime) {
+            return "gone";
+        }
+        return inspection.startTime === metadata.process_started_at
+            ? "alive"
+            : "gone";
+    };
+}
+function hasExactProcessIdentity(metadata) {
+    return (metadata.pid !== null &&
+        metadata.pid !== undefined &&
+        metadata.process_started_at !== null &&
+        metadata.process_started_at !== undefined &&
+        metadata.process_started_at.trim() !== "");
+}
+function sessionKindPriority(sessionKind) {
+    switch (sessionKind) {
+        case "human_guardian":
+            return 3;
+        case "mcp_harness":
+            return 2;
+        case "human_cli":
+            return 1;
+        default:
+            return 2;
+    }
+}
+function claimReasonForEvent(pendingEvent) {
+    if (!pendingEvent) {
+        return "open_claim";
+    }
+    return pendingEvent.event_type === "pass" ? "direct_pass" : "sequence";
+}
+function validateHandoff(handoff) {
+    if (!handoff || typeof handoff !== "object") {
+        throw new ProtocolError("invalid_handoff", "handoff must be an object.", { field: "handoff" });
+    }
+    if (!handoff.status || !handoff.status.trim()) {
+        throw new ProtocolError("invalid_handoff", "handoff.status must be non-empty.", { field: "status" });
+    }
+    if (!handoff.next_action || !handoff.next_action.trim()) {
+        throw new ProtocolError("invalid_handoff", "handoff.next_action must be non-empty.", { field: "next_action" });
+    }
+    if (handoff.artifacts !== undefined && !Array.isArray(handoff.artifacts)) {
+        throw new ProtocolError("invalid_handoff", "handoff.artifacts must be an array when provided.", { field: "artifacts" });
+    }
+}
+function assertNonEmpty(value, field) {
+    if (!value || !value.trim()) {
+        throw new ProtocolError("invalid_input", `${field} must be non-empty.`, {
+            field
+        });
+    }
+}
+function handoffTemplate() {
+    return {
+        status: "What I did:\nWhat I learned:\nOpen risks:",
+        next_action: "What the next agent should do next."
+    };
+}