letagents 0.12.20 → 0.12.22

package/shared/activation-routing.mjs

@@ -0,0 +1,468 @@
+import { normalizeRoutingHandle, normalizeRoutingSender, routingIdentityAliases, routingSenderAliasRows, routingSenderAliases, } from "./routing-aliases.mjs";
+import { parsePositivePgIntegerScopedId } from "./message-contracts.mjs";
+/** Send-time human fallback only; never use this to re-route historical reads. */
+export function humanConversationFallback(input) {
+    if (input.source !== "browser" || !input.publisherAccountId || input.publisherAgentKey || input.explicitlyAddressed)
+        return null;
+    const keys = [...new Set(input.registeredAgentKeys)];
+    if (keys.length > 0 && keys.length <= 2)
+        return { reason: "small_room", agentKeys: keys };
+    if (keys.length > 2 && input.recentAgentKey && keys.includes(input.recentAgentKey)) {
+        return { reason: "recent_conversation", agentKeys: [input.recentAgentKey] };
+    }
+    return null;
+}
+/**
+ * Repository events can contain text written by any external contributor.
+ * They remain visible room activity, but their text is never an instruction
+ * channel for a managed local worker.
+ */
+export function isUntrustedExternalActivationSource(source) {
+    return normalizeSender(source) === "github";
+}
+const NON_AGENT_AT_HANDLES = new Set([
+    "charset",
+    "container",
+    "counter-style",
+    "font-face",
+    "font-feature-values",
+    "font-palette-values",
+    "import",
+    "keyframes",
+    "layer",
+    "media",
+    "namespace",
+    "page",
+    "package",
+    "property",
+    "scope",
+    "starting-style",
+    "supports",
+    "types",
+    "viewport",
+]);
+const TASK_OWNER_FOLLOW_UP_PATTERNS = [
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:try again|retry|rerun|re-run|continue|proceed|go ahead|carry on)\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:open|create|make|raise)\s+(?:a\s+)?pr\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:push|merge|ship|fix|test|run|update)\s+(?:it|that|this|again|tests?|the\s+tests?|ci)\b/,
+    /\b(?:try again|open\s+(?:a\s+)?pr|create\s+(?:a\s+)?pr|make\s+(?:a\s+)?pr|push it|merge it|update it)\b/,
+];
+export function attachAgentMessageActivation(message, identity, context = {}) {
+    return {
+        ...message,
+        activation: {
+            for_current_agent: decideAgentMessageActivation(message, identity, context),
+        },
+    };
+}
+/**
+ * Send-time receipts are the activation authority. For a snapshot-bearing
+ * message, a receipt activates and the absence of one is the durable
+ * send-time "silent" — never re-promoted by re-running the router against
+ * later task/thread/session state, which would create a second authority.
+ * Only messages that predate routing snapshots keep the lazy per-reader
+ * decision, so legacy backlog mentions still activate rotated sessions.
+ */
+export function attachAgentMessageActivationsFromReceipts(messages, identity, receiptsMap, snapshotNumbers, context = {}) {
+    if (!identity || identity.session_kind !== "worker") {
+        return [...messages];
+    }
+    return messages.map((message) => {
+        const msgIdStr = String(message.id ?? "");
+        const msgNum = parsePositivePgIntegerScopedId(msgIdStr, "msg");
+        const receipt = msgNum !== null ? receiptsMap.get(msgNum) || receiptsMap.get(msgIdStr) : null;
+        if (receipt) {
+            const reason = receipt.activation_reason;
+            return {
+                ...message,
+                activation: {
+                    for_current_agent: {
+                        decision: "activate",
+                        reason: reason || "explicit_mention",
+                        addressed: true,
+                    },
+                },
+            };
+        }
+        // System failure rows are canonical silent control events. A routing
+        // snapshot with no receipt must not erase their diagnostic reason.
+        if (msgNum !== null
+            && snapshotNumbers.has(msgNum)
+            && normalizeSender(message.source) !== "managed_agent_failure") {
+            return {
+                ...message,
+                activation: {
+                    for_current_agent: {
+                        decision: "silent",
+                        reason: "unaddressed",
+                        addressed: false,
+                    },
+                },
+            };
+        }
+        return attachAgentMessageActivation(message, identity, context);
+    });
+}
+export function attachAgentMessageActivations(messages, identity, context = {}) {
+    if (!identity || identity.session_kind !== "worker") {
+        return [...messages];
+    }
+    return messages.map((message) => attachAgentMessageActivation(message, identity, context));
+}
+export function decideAgentMessageActivation(message, identity, context = {}) {
+    if (normalizeSender(message.source) === "managed_agent_failure"
+        || isUntrustedExternalActivationSource(message.source)) {
+        return decision("silent", "system_event");
+    }
+    const messageId = normalizedString(message.id);
+    const authoritativeLegacyDecision = context.authoritativeLegacyDecisions?.get(messageId);
+    if (authoritativeLegacyDecision)
+        return authoritativeLegacyDecision;
+    if (context.selfMessageIds !== undefined
+        ? context.selfMessageIds.has(messageId)
+        : senderMatchesIdentity(message.sender, identity)) {
+        return decision("silent", "self_message");
+    }
+    const mentions = extractMentionHandles(message.text);
+    if (mentions.some(isBroadcastHandle)) {
+        return decision("activate", "broadcast");
+    }
+    const authoritativeExplicitMentions = context.explicitMentionMessageIds;
+    if (authoritativeExplicitMentions !== undefined
+        ? authoritativeExplicitMentions.has(messageId)
+        : mentions.some((mention) => activationIdentityAliases(identity).has(normalizeMentionIdentityHandle(mention)))) {
+        return decision("activate", "explicit_mention");
+    }
+    if (hasBroadcastAddress(message.text)) {
+        return decision("activate", "broadcast");
+    }
+    if (mentions.some(isLikelyAgentMentionHandle)) {
+        return decision("silent", "explicit_other_mention");
+    }
+    const authoritativeThreadParticipantRootIds = context.threadParticipantRootIds;
+    const authoritativeReplyTargets = context.replyTargetMessageIds;
+    const hasAuthoritativeThreadMembership = isThreadReply(message)
+        && authoritativeThreadParticipantRootIds !== undefined;
+    if (authoritativeReplyTargets !== undefined
+        ? authoritativeReplyTargets.has(messageId)
+        : !hasAuthoritativeThreadMembership && senderMatchesIdentity(message.reply_to?.sender, identity)) {
+        return decision("activate", "reply_target");
+    }
+    if (isAgentReplyTarget(message.reply_to) && !isThreadReply(message)) {
+        return decision("silent", "other_reply_target");
+    }
+    if (isThreadReply(message)
+        && (hasAuthoritativeThreadMembership
+            ? authoritativeThreadParticipantRootIds.has(threadRootId(message))
+            : threadParticipantsIncludeIdentity(message, identity))) {
+        return decision("activate", "thread_participant");
+    }
+    const taskOwnerDecision = decideTaskOwnerActivation(message, identity, context);
+    if (taskOwnerDecision) {
+        return taskOwnerDecision;
+    }
+    return decision("unclear", "unaddressed");
+}
+function decision(decisionValue, reason) {
+    return {
+        decision: decisionValue,
+        reason,
+        addressed: decisionValue === "activate",
+    };
+}
+function isThreadReply(message) {
+    const ownId = normalizedString(message.id);
+    const rootId = threadRootId(message);
+    return Boolean(ownId && rootId && ownId !== rootId);
+}
+function threadRootId(message) {
+    return normalizedString(message.thread_root_id) || normalizedString(message.thread?.root_message_id);
+}
+function isAgentReplyTarget(replyTo) {
+    return normalizeSender(replyTo?.source) === "agent";
+}
+function threadParticipantsIncludeIdentity(message, identity) {
+    const senders = [
+        message.reply_to?.sender,
+        message.thread?.latest_reply?.sender,
+        ...(message.thread?.participants ?? []).map((participant) => participant.sender),
+    ];
+    return senders.some((sender) => senderMatchesIdentity(sender, identity));
+}
+function decideTaskOwnerActivation(message, identity, context) {
+    if (!isTaskOwnerFollowUp(message.text)) {
+        return null;
+    }
+    const owners = uniqueActiveWorkOwners(context.activeTaskLeases ?? []);
+    if (owners.length !== 1) {
+        return null;
+    }
+    const owner = owners[0];
+    if (senderMatchesLeaseOwner(message.sender, owner)) {
+        return null;
+    }
+    if (leaseOwnerMatchesIdentity(owner, identity)) {
+        return decision("activate", "task_owner");
+    }
+    if (identityOverlapsLeaseOwner(identity, owner)) {
+        return null;
+    }
+    return decision("silent", "task_owner");
+}
+function uniqueActiveWorkOwners(leases) {
+    const ownersByKey = new Map();
+    for (const lease of leases) {
+        if (lease.kind !== "work" || lease.status !== "active")
+            continue;
+        const key = leaseOwnerKey(lease);
+        if (!key)
+            continue;
+        ownersByKey.set(key, lease);
+    }
+    return [...ownersByKey.values()];
+}
+function leaseOwnerKey(lease) {
+    const sessionId = normalizedString(lease.agent_session_id);
+    if (sessionId)
+        return `session:${sessionId}`;
+    const instanceId = normalizedString(lease.agent_instance_id);
+    const agentKey = normalizeSender(lease.agent_key);
+    if (instanceId)
+        return `instance:${agentKey}:${instanceId}`;
+    if (agentKey)
+        return `agent:${agentKey}`;
+    const actorLabel = normalizeSender(lease.actor_label);
+    return actorLabel ? `label:${actorLabel}` : null;
+}
+function leaseOwnerMatchesIdentity(lease, identity) {
+    const leaseSessionId = normalizedString(lease.agent_session_id);
+    if (leaseSessionId) {
+        return leaseSessionId === normalizedString(identity.agent_session_id);
+    }
+    const leaseInstanceId = normalizedString(lease.agent_instance_id);
+    if (leaseInstanceId) {
+        return (leaseInstanceId === normalizedString(identity.agent_instance_id) &&
+            normalizeSender(lease.agent_key) === normalizeSender(identity.agent_key));
+    }
+    const leaseAgentKey = normalizeSender(lease.agent_key);
+    if (leaseAgentKey) {
+        return leaseAgentKey === normalizeSender(identity.agent_key);
+    }
+    return senderMatchesIdentity(lease.actor_label, identity);
+}
+function senderMatchesLeaseOwner(sender, lease) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    return leaseOwnerAliases(lease).has(normalizedSender);
+}
+function identityOverlapsLeaseOwner(identity, lease) {
+    const identityAliasesForOwner = aliasesForValues([
+        identity.actor_label,
+        identity.display_name,
+        identity.agent_key,
+        identity.agent_instance_id,
+        identity.agent_session_id,
+    ]);
+    for (const ownerAlias of leaseOwnerAliases(lease)) {
+        if (identityAliasesForOwner.has(ownerAlias)) {
+            return true;
+        }
+    }
+    return false;
+}
+function leaseOwnerAliases(lease) {
+    return aliasesForValues([
+        lease.actor_label,
+        ...String(lease.actor_label || "").split("|"),
+        lease.agent_key,
+        lease.agent_instance_id,
+        lease.agent_session_id,
+    ]);
+}
+function aliasesForValues(values) {
+    const aliases = new Set();
+    for (const value of values) {
+        const senderAlias = normalizeSender(value);
+        if (senderAlias)
+            aliases.add(senderAlias);
+        const handleAlias = normalizeHandle(value);
+        if (handleAlias)
+            aliases.add(handleAlias);
+    }
+    return aliases;
+}
+function senderMatchesIdentity(sender, identity) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    const aliases = activationIdentityAliases(identity);
+    if (aliases.has(normalizedSender))
+        return true;
+    return String(sender || "")
+        .split("|")
+        .some((part) => aliases.has(normalizeSender(part)));
+}
+export function activationIdentityAliases(identity) {
+    return routingIdentityAliases(identity);
+}
+/** Canonical aliases materialized from a historical message sender. */
+export function activationSenderAliases(sender, segmentLimit = 16) {
+    return routingSenderAliases(sender, segmentLimit);
+}
+/**
+ * Resolve identity-bearing addresses against the complete active room
+ * population. A display alias is authority only when it names one durable
+ * agent key globally; account/provider filtering happens after this step.
+ * Full historical sender labels take precedence over their pipe-delimited
+ * compatibility segments.
+ */
+export function resolveGloballyAddressedAgentKeys(message, identities) {
+    return createGlobalAgentAddressResolver(identities)(message);
+}
+/**
+ * Build the room-wide alias authority once, then resolve a page of legacy
+ * messages without rebuilding every active worker alias set per message.
+ */
+export function createGlobalAgentAddressResolver(identities, options = {}) {
+    const keysByAlias = new Map();
+    for (const identity of identities) {
+        const key = normalizedString(identity.agent_key);
+        if (!key)
+            continue;
+        for (const alias of activationIdentityAliases(identity)) {
+            const keys = keysByAlias.get(alias) ?? new Set();
+            keys.add(key);
+            keysByAlias.set(alias, keys);
+        }
+    }
+    const resolveExplicitMentionKey = (keys) => {
+        if (!keys || keys.size === 0)
+            return null;
+        if (keys.size === 1)
+            return keys.values().next().value;
+        const preferredMatches = [...keys].filter((key) => options.preferredExplicitMentionAgentKeys?.has(key));
+        if (preferredMatches.length !== 1)
+            return null;
+        const ownerScopes = new Set();
+        for (const key of keys) {
+            const scope = options.explicitMentionOwnerScopeByAgentKey?.get(key);
+            if (!scope)
+                return null;
+            ownerScopes.add(scope);
+        }
+        return ownerScopes.size === 1 ? preferredMatches[0] : null;
+    };
+    return (message) => {
+        const mentions = extractMentionHandles(message.text);
+        const broadcast = mentions.some(isBroadcastHandle) || hasBroadcastAddress(message.text);
+        const hasMention = mentions.some((mention) => !isBroadcastHandle(mention));
+        const hasAgentMention = mentions.some(isLikelyAgentMentionHandle);
+        const explicitMentionKeys = new Set();
+        for (const mention of mentions) {
+            if (isBroadcastHandle(mention))
+                continue;
+            const alias = normalizeMentionIdentityHandle(mention);
+            if (!alias)
+                continue;
+            const resolvedKey = resolveExplicitMentionKey(keysByAlias.get(alias));
+            if (resolvedKey)
+                explicitMentionKeys.add(resolvedKey);
+        }
+        const replyTargetKeys = new Set();
+        const replyAliases = normalizedString(message.reply_to?.source) === "agent"
+            ? routingSenderAliasRows(message.reply_to?.sender)
+            : [];
+        const matchingKeys = (full) => {
+            const keys = new Set();
+            for (const row of replyAliases) {
+                if (row.isFull !== full)
+                    continue;
+                for (const key of keysByAlias.get(row.alias) ?? [])
+                    keys.add(key);
+            }
+            return keys;
+        };
+        const fullMatches = matchingKeys(true);
+        const replyMatches = fullMatches.size > 0 ? fullMatches : matchingKeys(false);
+        if (replyMatches.size === 1)
+            replyTargetKeys.add(replyMatches.values().next().value);
+        const senderKeys = new Set();
+        const senderAliases = routingSenderAliasRows(message.sender);
+        const senderMatchingKeys = (full) => {
+            const keys = new Set();
+            for (const row of senderAliases) {
+                if (row.isFull !== full)
+                    continue;
+                for (const key of keysByAlias.get(row.alias) ?? [])
+                    keys.add(key);
+            }
+            return keys;
+        };
+        const senderFullMatches = senderMatchingKeys(true);
+        const senderMatches = senderFullMatches.size > 0
+            ? senderFullMatches
+            : senderMatchingKeys(false);
+        if (senderMatches.size === 1)
+            senderKeys.add(senderMatches.values().next().value);
+        return {
+            broadcast,
+            hasMention,
+            hasAgentMention,
+            explicitMentionKeys,
+            replyTargetKeys,
+            senderKeys,
+        };
+    };
+}
+/** Shared legacy task-follow-up classifier used by API and desktop overlays. */
+export function isTaskOwnerFollowUpMessageText(text) {
+    return isTaskOwnerFollowUp(text);
+}
+function extractMentionHandles(text) {
+    const raw = typeof text === "string" ? text : "";
+    const mentions = [];
+    for (const match of raw.matchAll(/(^|[\s([{:;,])@([A-Za-z0-9][A-Za-z0-9_.:-]*(?:\/[A-Za-z0-9][A-Za-z0-9_.-]*)*)/g)) {
+        mentions.push(match[2]);
+    }
+    return mentions;
+}
+function isBroadcastHandle(handle) {
+    const normalized = normalizeHandle(handle);
+    return normalized === "agents" || normalized === "everyone" || normalized === "room";
+}
+function isLikelyAgentMentionHandle(handle) {
+    const raw = normalizedString(handle);
+    if (!raw)
+        return false;
+    const normalized = raw.toLowerCase();
+    const firstSegment = normalized.split("/", 1)[0].replace(/_/g, "-");
+    if (normalized.startsWith("agent:"))
+        return true;
+    if (normalized.includes("/") && normalized === raw)
+        return false;
+    return !NON_AGENT_AT_HANDLES.has(firstSegment);
+}
+function hasBroadcastAddress(text) {
+    const raw = typeof text === "string" ? text.toLowerCase() : "";
+    return /\b(everyone|all agents|you guys|both of you|any agent|whoever owns this)\b/.test(raw);
+}
+function isTaskOwnerFollowUp(text) {
+    const raw = typeof text === "string" ? text.trim().toLowerCase() : "";
+    if (!raw)
+        return false;
+    return TASK_OWNER_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(raw));
+}
+function normalizedString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizeSender(value) {
+    return normalizeRoutingSender(value);
+}
+function normalizeHandle(value) {
+    return normalizeRoutingHandle(value);
+}
+function normalizeMentionIdentityHandle(value) {
+    const normalized = normalizeHandle(value);
+    return normalized.startsWith("agent:") ? normalized.slice("agent:".length) : normalized;
+}

package/shared/local-supervised-routing.d.mts

@@ -0,0 +1,9 @@
+import type { SqliteRoutingDatabase } from "./sqlite-thread-routing.mjs";
+export type LocalSupervisedMessageRow = {
+  room_id: string; number: number; sender: string; text: string; source: string | null;
+  publisher_agent_key: string | null; thread_root_number: number | null; reply_to_number: number | null;
+  control_authorized: number | null; timestamp: string; sync_key: string | null;
+};
+export function ensureLocalSupervisedRoutingSchema(db: SqliteRoutingDatabase): void;
+export function captureLocalSupervisedRouting(db: SqliteRoutingDatabase, row: LocalSupervisedMessageRow): void;
+export function runLocalSupervisedMessageWrite<T>(db: SqliteRoutingDatabase, roomId: string, threadRootNumber: number | null, work: () => T): Promise<T>;

package/shared/local-supervised-routing.mjs

@@ -0,0 +1,93 @@
+import { createGlobalAgentAddressResolver, decideAgentMessageActivation, humanConversationFallback } from "./activation-routing.mjs";
+import { readProjectedLocalThreadRoutingAgentKeys, ensureRequestedRootsProjected, runLocalSqliteWriteTransactionAsync, LocalThreadRoutingProjectionChangedError } from "./sqlite-thread-routing.mjs";
+import { parseSupervisedReplySourceNumber } from "./message-contracts.mjs";
+export function ensureLocalSupervisedRoutingSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS local_supervisor_message_routes (
+    room_id TEXT NOT NULL, message_id TEXT NOT NULL, routes_json TEXT NOT NULL,
+    PRIMARY KEY(room_id, message_id)
+  ) STRICT`);
+}
+function recentRecipient(db, message) {
+    const recent = db.prepare(`SELECT * FROM local_chat_messages WHERE room_id=? AND number<?
+    ORDER BY number DESC LIMIT 50`).all(message.room_id, message.number)
+        .filter(row => Date.parse(String(row.timestamp)) >= Date.parse(message.timestamp) - 30 * 60_000);
+    const human = recent.find(row => row.source === "browser" && !row.publisher_agent_key
+        && row.control_authorized === 1 && row.thread_root_number === null);
+    if (!human)
+        return null;
+    const captured = db.prepare("SELECT routes_json FROM local_supervisor_message_routes WHERE room_id=? AND message_id=?")
+        .get(message.room_id, `msg_${human.number}`);
+    if (!captured)
+        return null;
+    const recipients = Object.entries(JSON.parse(String(captured.routes_json)))
+        .filter(([, route]) => route.decision === "activate").map(([key]) => key);
+    if (recipients.length === 1)
+        return recipients[0];
+    const answered = new Set();
+    for (const reply of recent) {
+        const key = String(reply.publisher_agent_key || "");
+        const prefix = `local-supervised:${key}:`;
+        const receipt = String(reply.sync_key || "");
+        if (reply.source === "agent" && Number(reply.number) > Number(human.number)
+            && recipients.includes(key) && (reply.reply_to_number === human.number
+            || (receipt.startsWith(prefix)
+                && parseSupervisedReplySourceNumber(receipt.slice(prefix.length)) === human.number)))
+            answered.add(key);
+    }
+    return answered.size === 1 ? [...answered][0] : null;
+}
+/** Capture all recipients atomically with the message, including the empty-room case. */
+export function captureLocalSupervisedRouting(db, row) {
+    const reply = row.reply_to_number ? db.prepare("SELECT * FROM local_chat_messages WHERE room_id=? AND number=?")
+        .get(row.room_id, row.reply_to_number) : null;
+    const registered = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='local_supervisor_grants'").get();
+    const identities = registered
+        ? db.prepare("SELECT agent_key,display_name FROM local_supervisor_grants WHERE room_id=? AND revoked_at IS NULL ORDER BY entry_id")
+            .all(row.room_id).map(grant => ({ agent_key: String(grant.agent_key), display_name: String(grant.display_name),
+            actor_label: String(grant.display_name), agent_instance_id: null, agent_session_id: null, session_kind: "worker" })) : [];
+    const id = `msg_${row.number}`;
+    const rootId = `msg_${row.thread_root_number ?? row.number}`;
+    const threadReply = row.thread_root_number !== null && row.thread_root_number !== row.number;
+    const message = { id, text: row.text, sender: row.sender, source: row.source,
+        thread_root_id: threadReply ? rootId : null, reply_to: reply ? { id: `msg_${reply.number}`, sender: reply.sender } : null };
+    const address = createGlobalAgentAddressResolver(identities)(message);
+    const participants = threadReply ? readProjectedLocalThreadRoutingAgentKeys(db, row.room_id, [row.thread_root_number], identities.map(identity => ({ agentKey: identity.agent_key, displayName: identity.display_name, actorLabel: identity.actor_label })))
+        .get(row.thread_root_number) ?? new Set() : new Set();
+    const fallback = humanConversationFallback({ source: row.source,
+        publisherAccountId: row.control_authorized === 1 ? "local-owner" : null, publisherAgentKey: row.publisher_agent_key,
+        explicitlyAddressed: address.broadcast || address.hasAgentMention || threadReply || Boolean(reply),
+        registeredAgentKeys: identities.map(identity => identity.agent_key),
+        recentAgentKey: identities.length > 2 ? recentRecipient(db, row) : null });
+    const routes = {};
+    for (const identity of identities) {
+        const key = identity.agent_key;
+        let decision = decideAgentMessageActivation(message, identity, {
+            selfMessageIds: new Set(row.source === "agent" && row.publisher_agent_key === key ? [id] : []),
+            explicitMentionMessageIds: new Set(address.explicitMentionKeys.has(key) ? [id] : []),
+            replyTargetMessageIds: new Set(!threadReply && (reply?.publisher_agent_key
+                ? reply.publisher_agent_key === key : address.replyTargetKeys.has(key)) ? [id] : []),
+            threadParticipantRootIds: new Set(participants.has(key) ? [rootId] : []),
+        });
+        if (row.source === "agent" && !row.publisher_agent_key)
+            decision = { decision: "silent", reason: "unaddressed", addressed: false };
+        if (decision.reason === "unaddressed" && fallback?.agentKeys.includes(key)) {
+            decision = { decision: "activate", reason: fallback.reason, addressed: true };
+        }
+        routes[key] = decision;
+    }
+    db.prepare("INSERT INTO local_supervisor_message_routes(room_id,message_id,routes_json) VALUES(?,?,?)")
+        .run(row.room_id, id, JSON.stringify(routes));
+}
+
+/** Repair outside the write lock; a concurrent invalidation rolls back the entire send. */
+export async function runLocalSupervisedMessageWrite(db, roomId, threadRootNumber, work) {
+  const deadline = performance.now() + 2_000;
+  for (;;) {
+    if (threadRootNumber) await ensureRequestedRootsProjected(db, roomId, [threadRootNumber]);
+    try {
+      return await runLocalSqliteWriteTransactionAsync(db, work);
+    } catch (error) {
+      if (!(error instanceof LocalThreadRoutingProjectionChangedError) || performance.now() >= deadline) throw error;
+    }
+  }
+}

package/shared/local-work-leases.d.mts

@@ -0,0 +1,24 @@
+import type { SqliteRoutingDatabase as SqliteDatabase } from './sqlite-thread-routing.mjs';
+export type LocalWorkLeaseWorker = {
+  agent_key: string; session_id: string; actor_label: string; agent_instance_id?: string | null; supervised?: boolean;
+};
+export type LocalWorkLease = {
+  id: string; room_id: string; task_id: string; kind: 'work'; status: string;
+  agent_key: string; agent_session_id: string; agent_instance_id: string | null; actor_label: string;
+  epoch: number; created_at: string; updated_at: string; last_heartbeat_at: string;
+  expires_at: string | null; revoked_reason: string | null;
+};
+export type LocalWorkLeaseAction = {
+  action: 'release' | 'handoff'; lease_id?: string | null; epoch?: number;
+  target_actor_key?: string | null; target_actor_instance_id?: string | null; target_agent_session_id?: string | null;
+};
+export function ensureLocalWorkLeaseSchema(db: SqliteDatabase): void;
+export function readLocalWorkLeases(db: SqliteDatabase, roomId: string, taskId: string): LocalWorkLease[];
+export function assertLocalWorkLeaseWorker(db: SqliteDatabase, roomId: string, worker: LocalWorkLeaseWorker): boolean;
+export function claimLocalWorkLease(db: SqliteDatabase, roomId: string, taskId: string, worker: LocalWorkLeaseWorker): LocalWorkLease;
+export function assertLocalTaskLeaseMutation(db: SqliteDatabase, task: Record<string, unknown>, worker: LocalWorkLeaseWorker,
+  expected?: Pick<LocalWorkLease, 'id' | 'epoch'> | null): void;
+export function changeLocalWorkLease(db: SqliteDatabase, roomId: string, taskId: string, input: LocalWorkLeaseAction,
+  worker: LocalWorkLeaseWorker | null): { released_lease: LocalWorkLease; new_lease: LocalWorkLease | null };
+export function endLocalWorkerLeases(db: SqliteDatabase, sessionId: string, now: string): void;
+export function heartbeatLocalWorkLeases(db: SqliteDatabase, sessionId: string, now: string): Array<{id: string; epoch: number}>;