letagents 0.12.13 → 0.12.14

package/dist/mcp/server/runtime/agent-sessions.js

@@ -5,7 +5,7 @@ import { normalizeAgentBaseName } from "../../../shared/codenames.js";
 import { formatOwnerAttribution } from "../../../shared/agent-identity.js";
 import { LETAGENTS_AGENT_SESSION_ID_HEADER, LETAGENTS_AGENT_SESSION_TOKEN_HEADER, } from "../../../shared/request-headers.js";
 import { AGENT_INSTANCE_UUID, detectAgentIdeLabel, detectAgentRuntimeLabel, ensureAgentIdentity, } from "./identity.js";
-import { isSupervisedBoundedTurn, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
 import { resolveCurrentSupervisedWorkerSession } from "./supervisor-bridge.js";
 import { getDaemonToolExecutionContext, getRuntimeWorkingDirectory } from "./daemon-tool-context.js";
 // A worker bearer already represents a server-side worker session. This local
@@ -166,7 +166,7 @@ export async function resolveWorkerToolIdentity(input) {
     }
     const agentSession = input.agentSessionId
         ? requireWorkerAgentSession(input.roomId, input.agentSessionId)
-        : input.roomId && !isSupervisedBoundedTurn() && await isLocalRoomStorageEnabled(input.roomId)
+        : input.roomId && !hasSupervisedWorkerAuthority() && await isLocalRoomStorageEnabled(input.roomId)
             ? await ensureLocalWorkerAgentSession(input.roomId)
             : requireWorkerAgentSession(input.roomId, input.agentSessionId);
     return {

package/dist/mcp/server/runtime/execution-profile.js

@@ -1,5 +1,6 @@
 export const EXECUTION_PROFILES = [
     "supervised_room_turn",
+    "supervised_mcp_polling",
     "autonomous_mcp_worker",
     "interactive_desktop",
 ];

package/dist/mcp/server/runtime/presence.js

@@ -4,7 +4,7 @@ import { isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, touchRoo
 import { apiCall, isMissingRouteError } from "./api.js";
 import { agentSessionCredentials, identityFromAgentSession } from "./agent-sessions.js";
 import { getSessionLivenessRegistration } from "./identity.js";
-import { isSupervisedBoundedTurn } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./worker-bearer.js";
 const roomPresenceByIdentity = new Map();
 export function getRememberedRoomPresence(roomId, identity) {
     if (!roomId || !identity) {
@@ -19,7 +19,7 @@ export async function syncRoomPresence(roomId, identity, presence, agentSession)
     }
     roomPresenceByIdentity.set(getRoomIdentityPresenceCacheKey(roomId, resolvedIdentity.actor_label), presence);
     const { localRoomId, cloudRoomId } = await resolveLocalRoomStorageIdentifiers(roomId);
-    if (!isSupervisedBoundedTurn() && await isLocalRoomStorageEnabled(roomId)) {
+    if (!hasSupervisedWorkerAuthority() && await isLocalRoomStorageEnabled(roomId)) {
         touchRoomSession(localRoomId || roomId);
         return;
     }
@@ -39,7 +39,7 @@ export async function syncRoomPresence(roomId, identity, presence, agentSession)
                 ...agentSessionCredentials(agentSession),
             }),
         });
-        if (!isSupervisedBoundedTurn())
+        if (!hasSupervisedWorkerAuthority())
             touchRoomSession(apiRoomId);
     }
     catch (error) {

package/dist/mcp/server/runtime/room-api.js

@@ -4,9 +4,9 @@ import { apiCall, isMissingRouteError, } from "./api.js";
 import { maybeHandleRepoRoomAuthRequired } from "./device-auth.js";
 import { getLastMessageId } from "./messages.js";
 import { currentRoom, getCurrentSupervisedRoomAuthority } from "./room-state.js";
-import { isSupervisedBoundedTurn } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./worker-bearer.js";
 export async function roomScopedApiCall(input) {
-    const supervised = isSupervisedBoundedTurn();
+    const supervised = hasSupervisedWorkerAuthority();
     const exactRoomAuthority = supervised ? getCurrentSupervisedRoomAuthority() : null;
     if (supervised && (!exactRoomAuthority || input.room_id !== exactRoomAuthority)) {
         throw new Error("The daemon-supervised API request is missing its exact per-call room authority.");

package/dist/mcp/server/runtime/room-state.js

@@ -3,7 +3,7 @@ import { getStoredAgentIdentity, saveRoomSession, touchRoomSession, } from "../.
 import { getCanonicalRoomWebPath, } from "../../room-id.js";
 import { getApiUrl, getLetagentsToken } from "./api.js";
 import { AGENT_INSTANCE_UUID, currentAgentIdentity, currentAgentIdentityKey, } from "./identity.js";
-import { isSupervisedBoundedTurn } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./worker-bearer.js";
 import { getCurrentSupervisedRoomAuthority, runWithSupervisedRoomAuthority, } from "./supervised-room-authority.js";
 let mcpServer = null;
 let sseClient = null;
@@ -92,7 +92,7 @@ export function toPublicRoomResponse(response, fallbackRoomId) {
 }
 export function rememberRoom(state, lastMessageId) {
     currentRoom = state;
-    if (isSupervisedBoundedTurn())
+    if (hasSupervisedWorkerAuthority())
         return state;
     saveRoomSession({
         room_id: state.room_id,
@@ -123,7 +123,7 @@ export function rememberRoom(state, lastMessageId) {
     return state;
 }
 export function touchCurrentRoom(lastMessageId) {
-    if (isSupervisedBoundedTurn())
+    if (hasSupervisedWorkerAuthority())
         return;
     if (!currentRoom) {
         return;
@@ -131,7 +131,7 @@ export function touchCurrentRoom(lastMessageId) {
     touchRoomSession(currentRoom.room_id, lastMessageId);
 }
 export function getTargetRoomId(roomId) {
-    if (isSupervisedBoundedTurn()) {
+    if (hasSupervisedWorkerAuthority()) {
         const exactRoomAuthority = getCurrentSupervisedRoomAuthority();
         if (!exactRoomAuthority) {
             throw new Error("The daemon-supervised tool has not received its exact room authority.");
@@ -162,7 +162,7 @@ export function toPublicCurrentRoomState() {
  * repository inspection and can safely rebind after a durable room move.
  */
 export function runWithCurrentSupervisedRoom(roomId, callback) {
-    if (!isSupervisedBoundedTurn()) {
+    if (!hasSupervisedWorkerAuthority()) {
         throw new Error("Only a daemon-supervised bounded turn can bind supervisor room authority.");
     }
     const normalized = roomId.trim();
@@ -172,7 +172,7 @@ export function runWithCurrentSupervisedRoom(roomId, callback) {
     return runWithSupervisedRoomAuthority(normalized, callback);
 }
 export function getFallbackProjectId() {
-    if (isSupervisedBoundedTurn())
+    if (hasSupervisedWorkerAuthority())
         return null;
     return currentRoom?.project_id ?? null;
 }

package/dist/mcp/server/runtime/rooms.js

@@ -9,7 +9,7 @@ import { ensureAgentIdentity, toPublicAgentIdentity, withAgentIdentity, } from "
 import { withJoinRoomAgentPrompt } from "./messages.js";
 import { syncRoomPresence } from "./presence.js";
 import { rememberRoom, toPublicRoomResponse, toRoomState, } from "./room-state.js";
-import { isSupervisedBoundedTurn, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
 export function normalizeJoinSessionMode(value) {
     return String(value || "").trim().toLowerCase() === "live" ? "live" : "current";
 }
@@ -30,7 +30,7 @@ function parseGeneratedGitRefRoomIdentifier(identifier) {
     };
 }
 export async function joinRoomIdentifier(identifier, joinedVia, options = {}) {
-    if (isSupervisedBoundedTurn()) {
+    if (hasSupervisedWorkerAuthority()) {
         throw new Error("Room joins and creation are disabled during a daemon-supervised bounded turn.");
     }
     const roomId = joinedVia === "join_code" ? normalizeInviteCode(identifier) : identifier.trim();
@@ -191,7 +191,7 @@ export async function joinRoomIdentifierWithoutImplicitGitRefCreate(identifier,
     }));
 }
 export async function createInviteRoom() {
-    if (isSupervisedBoundedTurn()) {
+    if (hasSupervisedWorkerAuthority()) {
         throw new Error("Room joins and creation are disabled during a daemon-supervised bounded turn.");
     }
     const project = await apiCall("/projects", { method: "POST" });

package/dist/mcp/server/runtime/supervisor-bridge.js

@@ -6,12 +6,86 @@ import { join } from "node:path";
 import { parsePositivePgIntegerScopedId } from "../../../../shared/message-contracts.mjs";
 import { getCurrentSupervisedRoomAuthority } from "./supervised-room-authority.js";
 const NEGOTIATION_PROTOCOL_VERSION = 1;
-const SUPPORTED_SUPERVISOR_PROTOCOL_VERSIONS = new Set([1, 2]);
+const SUPPORTED_SUPERVISOR_PROTOCOL_VERSIONS = new Set([1, 2, 3]);
 const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
 const CONFIRMED_BINDING_VERIFY_TIMEOUT_MS = 250;
 const SUPERVISOR_CONTEXT_FILE = ".letagents-supervisor-context.json";
 const WORK_ATTEMPT_MARKER_FILE = ".letagents-work-attempt.json";
 const MAX_SUPERVISOR_CONTEXT_BYTES = 4 * 1024;
+// An SDK request id is unique only within this MCP process lifetime.
+const CUSTODIAL_POLLING_PROCESS_INCARNATION_ID = randomUUID();
+/** Release reuses BEFORE's exact generation; it never authorizes against a successor. */
+export async function authorizeCustodialPolling(toolName, prior, env = process.env, options = {}, waitRequest) {
+    const wait = waitRequest ? { ...waitRequest } : undefined;
+    if (toolName === "wait_for_messages") {
+        if (!wait || !(typeof wait.mcpRequestId === "string" || Number.isSafeInteger(wait.mcpRequestId))) {
+            throw new Error("Custodial wait is missing its exact MCP request id.");
+        }
+        if (!(wait.roomCursor === null || (typeof wait.roomCursor === "string" && parseRoomMessageNumber(wait.roomCursor) !== null))
+            || (prior && (!prior.wait || prior.wait.processIncarnationId !== CUSTODIAL_POLLING_PROCESS_INCARNATION_ID
+                || prior.wait.mcpRequestId !== wait.mcpRequestId || typeof wait.offeredFrontier !== "string"
+                || parseRoomMessageNumber(wait.offeredFrontier) === null || prior.roomCursor === null
+                || parseRoomMessageNumber(wait.offeredFrontier) < parseRoomMessageNumber(prior.roomCursor)))) {
+            throw new Error("Custodial wait receipt does not match its original invocation and cursor.");
+        }
+    }
+    else if (wait || prior?.wait)
+        throw new Error("Only custodial wait may acknowledge or offer a cursor.");
+    if (env.LETAGENTS_EXECUTION_PROFILE?.trim() !== "supervised_mcp_polling")
+        throw new Error("Custodial polling profile required.");
+    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() === "1"
+        || env.LETAGENTS_TOKEN?.trim() || env.LETAGENTS_AGENT_SESSION_BEARER?.trim()) {
+        throw new Error("Custodial polling refuses bounded flags and environment credentials.");
+    }
+    const coordinates = prior?.coordinates ?? await resolveSupervisorCoordinates(supervisedContextSession(env), env, options);
+    if (!coordinates?.roomId || !coordinates.agentSessionId)
+        throw new Error("Custodial polling lacks exact worker coordinates.");
+    if ((wait?.requestedRoomId && wait.requestedRoomId !== coordinates.roomId)
+        || (wait?.requestedAgentSessionId && wait.requestedAgentSessionId !== coordinates.agentSessionId)) {
+        throw new Error("Custodial wait room or worker identity does not match its exact authority.");
+    }
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const negotiated = prior?.negotiated ?? await negotiateSupervisor(coordinates.socketPath, timeoutMs);
+    if (!negotiated.custodialPollingV1 || negotiated.generation === null)
+        throw new Error("Daemon does not support custodial_polling_v1.");
+    if (wait && !negotiated.custodialPollingOffersV1)
+        throw new Error("Daemon does not support custodialPollingOffersV1; refusing an unjournaled wait.");
+    const apiUrl = prior?.apiUrl ?? env.LETAGENTS_API_URL?.trim();
+    if (!apiUrl)
+        throw new Error("Custodial polling requires an explicit API URL.");
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: negotiated.protocolVersion, id: randomUUID(), method: "supervisor.authorize_custodial_polling",
+        params: {
+            entry_id: coordinates.entryId, room_id: coordinates.roomId, work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId, agent_session_id: coordinates.agentSessionId,
+            daemon_generation: negotiated.generation, api_url: apiUrl, contract: "custodial_polling_v1",
+            phase: prior ? "release" : "before", tool_name: toolName,
+            ...(prior ? { expected_configuration_revision: prior.configurationRevision } : {}),
+            ...(wait ? {
+                process_incarnation_id: CUSTODIAL_POLLING_PROCESS_INCARNATION_ID, mcp_request_id: wait.mcpRequestId,
+                ...(prior ? { expected_activation_id: prior.wait.activationId, expected_binding_epoch: prior.wait.bindingEpoch,
+                    input_cursor: prior.roomCursor, offered_frontier: wait.offeredFrontier } : { room_cursor: wait.roomCursor }),
+            } : {}),
+        },
+    }, timeoutMs);
+    const result = response.result;
+    if (!response.ok || response.version !== negotiated.protocolVersion || !result || result.status !== "authorized" || result.contract !== "custodial_polling_v1"
+        || result.room_id !== coordinates.roomId || result.agent_session_id !== coordinates.agentSessionId
+        || !Number.isSafeInteger(result.configuration_revision) || Number(result.configuration_revision) < 1
+        || (prior && result.configuration_revision !== prior.configurationRevision)
+        || (wait && (typeof result.activation_id !== "string" || !result.activation_id.trim()
+            || !Number.isSafeInteger(result.binding_epoch) || Number(result.binding_epoch) < 1
+            || typeof result.room_cursor !== "string"
+            || (prior && (result.activation_id !== prior.wait.activationId || result.binding_epoch !== prior.wait.bindingEpoch
+                || result.room_cursor !== prior.roomCursor))))
+        || !(result.room_cursor === null || (typeof result.room_cursor === "string" && parseRoomMessageNumber(result.room_cursor) !== null))) {
+        throw new Error("Custodial polling authority was rejected or became stale.");
+    }
+    return { coordinates, negotiated, apiUrl, roomId: coordinates.roomId, agentSessionId: coordinates.agentSessionId,
+        roomCursor: result.room_cursor, configurationRevision: Number(result.configuration_revision),
+        ...(wait ? { wait: { processIncarnationId: CUSTODIAL_POLLING_PROCESS_INCARNATION_ID, mcpRequestId: wait.mcpRequestId,
+                activationId: String(result.activation_id), bindingEpoch: Number(result.binding_epoch) } } : {}) };
+}
 const confirmedBindingsBySession = new Map();
 const confirmedRequestsBySession = new Map();
 const confirmedProtocolsBySession = new Map();
@@ -184,7 +258,8 @@ async function requireCurrentSupervisedCoordinates(env, options) {
  * authority for the exact worker session identity.
  */
 export async function borrowCurrentSupervisedWorkerCredential(env = process.env, options = {}) {
-    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1") {
+    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1"
+        && env.LETAGENTS_EXECUTION_PROFILE?.trim() !== "supervised_mcp_polling") {
         return { state: "not_supervised" };
     }
     const seed = supervisedContextSession(env);
@@ -728,7 +803,9 @@ async function negotiateSupervisor(socketPath, timeoutMs) {
     const daemonIdentity = hasCompleteIdentity
         ? [result.generation, result.pid, result.started_at].join(":")
         : null;
-    return { protocolVersion, daemonIdentity, generation: hasCompleteIdentity ? Number(result.generation) : null };
+    return { protocolVersion, daemonIdentity, generation: hasCompleteIdentity ? Number(result.generation) : null,
+        custodialPollingV1: result.capabilities?.custodialPollingV1 === true,
+        custodialPollingOffersV1: result.capabilities?.custodialPollingOffersV1 === true };
 }
 function supervisorRequest(socketPath, request, timeoutMs) {
     return new Promise((resolve, reject) => {

package/dist/mcp/server/runtime/tool-surface-policy.js

@@ -1,4 +1,11 @@
 const TOOL_SURFACE_BY_PROFILE = {
+    supervised_mcp_polling: {
+        agentSessionLifecycle: false,
+        deliveryLoop: true,
+        onboarding: false,
+        rental: false,
+        roomResume: false,
+    },
     supervised_room_turn: {
         agentSessionLifecycle: false,
         deliveryLoop: false,

package/dist/mcp/server/runtime/worker-bearer.js

@@ -13,13 +13,17 @@ export function getWorkerBearerRuntime() {
     const bearer = process.env.LETAGENTS_AGENT_SESSION_BEARER?.trim();
     const supervised = process.env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() === "1";
     const profile = process.env.LETAGENTS_EXECUTION_PROFILE?.trim();
+    const polling = profile === "supervised_mcp_polling";
     if (supervised !== (profile === "supervised_room_turn")) {
         return {
             mode: "invalid",
             error: "LETAGENTS_EXECUTION_PROFILE=supervised_room_turn and LETAGENTS_SUPERVISED_BOUNDED_TURNS=1 must be configured together.",
         };
     }
-    if (!bearer && !supervised)
+    if (polling && (bearer || process.env.LETAGENTS_TOKEN?.trim())) {
+        return { mode: "invalid", error: "Custodial polling refuses environment credentials; borrow exact daemon worker authority." };
+    }
+    if (!bearer && !supervised && !polling)
         return { mode: "owner" };
     if (bearer && supervised) {
         return {
@@ -69,6 +73,13 @@ export function requireValidWorkerBearerRuntime() {
     return runtime;
 }
 export function isSupervisedBoundedTurn() {
+    return hasSupervisedWorkerAuthority() && !isCustodialPolling();
+}
+export function isCustodialPolling() {
+    return process.env.LETAGENTS_EXECUTION_PROFILE?.trim() === "supervised_mcp_polling";
+}
+/** Credential custody is independent of who owns room delivery. */
+export function hasSupervisedWorkerAuthority() {
     return requireValidWorkerBearerRuntime().mode === "supervised";
 }
 export function workerModeDisabledToolResult(toolDescription = "This owner-auth onboarding tool") {

package/dist/mcp/server/runtime-contract.js

@@ -19,6 +19,7 @@ export function letAgentsRuntimeContract() {
     return {
         format: 1,
         profiles: {
+            supervised_mcp_polling: { contract: "custodial_polling_v1", tools: registeredToolNames("supervised_mcp_polling", "codex") },
             cursor_supervised_room_turn: {
                 tools: registeredToolNames("supervised_room_turn", "cursor"),
             },

package/dist/mcp/server/runtime.js

@@ -2,13 +2,13 @@
 // in src/mcp/server/runtime/* so tool modules can import focused responsibilities
 // without turning this file back into the runtime god module.
 import { isLocalRoomStorageEnabled as isStoredLocalRoomStorageEnabled, touchRoomSession as touchStoredRoomSession, } from "../local-state.js";
-import { isSupervisedBoundedTurn } from "./runtime/worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./runtime/worker-bearer.js";
 /** A daemon-supervised turn must always use its exact cloud worker route. */
 export async function isLocalRoomStorageEnabled(roomId) {
-    return !isSupervisedBoundedTurn() && isStoredLocalRoomStorageEnabled(roomId);
+    return !hasSupervisedWorkerAuthority() && isStoredLocalRoomStorageEnabled(roomId);
 }
 export function touchRoomSession(roomId, lastMessageId) {
-    if (!isSupervisedBoundedTurn())
+    if (!hasSupervisedWorkerAuthority())
         touchStoredRoomSession(roomId, lastMessageId);
 }
 export { API_URL, ApiError, apiCall, getAuthorizationHeader, getLetagentsToken, isMissingRouteError, parseApiErrorPayload, resolveApiPath, } from "./runtime/api.js";

package/dist/mcp/server/supervised-tool-facade.js

@@ -1,5 +1,6 @@
+import { parsePositivePgIntegerScopedId } from "../../../shared/message-contracts.mjs";
 import { runWithCurrentSupervisedRoom } from "./runtime/room-state.js";
-import { completeCurrentSupervisedEffect, executeCurrentSupervisedTool, prepareCurrentSupervisedEffect, } from "./runtime/supervisor-bridge.js";
+import { completeCurrentSupervisedEffect, authorizeCustodialPolling, executeCurrentSupervisedTool, prepareCurrentSupervisedEffect, } from "./runtime/supervisor-bridge.js";
 const READ_TOOLS = new Set([
     "get_current_room",
     "check_repo",
@@ -22,6 +23,40 @@ export function supervisedToolIsMutation(toolName) {
 // frames. A read result can be returned live to the provider without copying
 // the entire payload into the durable effect journal.
 const MAX_DURABLE_READ_RESULT_BYTES = 16 * 1024;
+/** Receipt only the bounded page actually returned by wait, never an API tail
+ * beyond that page or a cursor inferred from its last visible message. */
+function custodialWaitFrontier(result, inputCursor, roomId) {
+    const content = result.content;
+    if (result.isError || content.length !== 1 || content[0]?.type !== "text")
+        throw new Error("Custodial wait returned no valid bounded page.");
+    let output;
+    try {
+        output = JSON.parse(content[0].text);
+    }
+    catch {
+        throw new Error("Custodial wait returned no valid bounded page.");
+    }
+    if (!output || Array.isArray(output) || !Array.isArray(output.messages)
+        || (output.room_id !== undefined && output.room_id !== roomId))
+        throw new Error("Custodial wait returned no valid bounded page.");
+    const noProgress = output.messages.length === 0 && (output.truncated === undefined || output.truncated === false)
+        && (output.omitted_message_count === undefined || output.omitted_message_count === 0)
+        && (output.skipped_message_count === undefined || output.skipped_message_count === 0)
+        && (output.skipped_message_ids === undefined || (Array.isArray(output.skipped_message_ids) && output.skipped_message_ids.length === 0));
+    const frontier = output.last_observed_message_id;
+    if (frontier === undefined || frontier === null) {
+        if (!noProgress) {
+            throw new Error("Custodial wait is missing its bounded observed frontier.");
+        }
+        return inputCursor;
+    }
+    const number = parsePositivePgIntegerScopedId(frontier, "msg");
+    const inputNumber = parsePositivePgIntegerScopedId(inputCursor, "msg");
+    if (number === null || inputNumber === null || number < inputNumber || (number === inputNumber && !noProgress)) {
+        throw new Error("Custodial wait returned an invalid observed frontier.");
+    }
+    return String(frontier);
+}
 function instruction(text, data = {}) {
     const payload = { ...data, instruction: text };
     return {
@@ -47,7 +82,7 @@ const productionDependencies = {
     withRoom: runWithCurrentSupervisedRoom,
 };
 export function profileAwareToolServer(server, profile, dependencies = productionDependencies, supervisedProvider = process.env.LETAGENTS_SUPERVISOR_PROVIDER?.trim() || null) {
-    if (profile !== "supervised_room_turn")
+    if (profile !== "supervised_room_turn" && profile !== "supervised_mcp_polling")
         return server;
     return new Proxy(server, {
         get(target, property, receiver) {
@@ -61,6 +96,43 @@ export function profileAwareToolServer(server, profile, dependencies = productio
                 if (typeof callback !== "function")
                     throw new Error(`Tool ${name} has no callback.`);
                 const wrapped = async (...call) => {
+                    if (profile === "supervised_mcp_polling") {
+                        const authorize = dependencies.authorizePolling ?? ((toolName, prior, wait) => authorizeCustodialPolling(toolName, prior, process.env, {}, wait));
+                        const input = call[0];
+                        const extra = (call.length > 1 ? call.at(-1) : undefined);
+                        let wait;
+                        if (name === "wait_for_messages") {
+                            const requestId = extra?.requestId;
+                            if (!(typeof requestId === "string" || (typeof requestId === "number" && Number.isSafeInteger(requestId)))) {
+                                throw new Error("Custodial wait is missing its exact MCP request id.");
+                            }
+                            if (input?.after_message_id != null && typeof input.after_message_id !== "string")
+                                throw new Error("Custodial wait requires a valid requested cursor.");
+                            if ((input?.room_id != null && typeof input.room_id !== "string")
+                                || (input?.agent_session_id != null && typeof input.agent_session_id !== "string"))
+                                throw new Error("Custodial wait requires valid requested identity.");
+                            wait = { mcpRequestId: requestId, roomCursor: input?.after_message_id ?? null,
+                                ...(typeof input?.room_id === "string" ? { requestedRoomId: input.room_id } : {}),
+                                ...(typeof input?.agent_session_id === "string" ? { requestedAgentSessionId: input.agent_session_id } : {}) };
+                        }
+                        const authority = await authorize(name, undefined, wait);
+                        return dependencies.withRoom(authority.roomId, async () => {
+                            if (input?.room_id && input.room_id !== authority.roomId)
+                                throw new Error("Custodial tool room does not match its exact authority.");
+                            if (name === "wait_for_messages") {
+                                if (!authority.roomCursor)
+                                    throw new Error("Custodial polling has no durable cursor; refusing a tail fallback.");
+                                call[0] = { ...input, after_message_id: authority.roomCursor };
+                            }
+                            const result = await callback(...call);
+                            if (wait)
+                                await authorize(name, authority, { ...wait,
+                                    offeredFrontier: custodialWaitFrontier(result, authority.roomCursor, authority.roomId) });
+                            else if (name === "read_messages")
+                                await authorize(name, authority);
+                            return result;
+                        });
+                    }
                     const extra = (call.at(-1) ?? {});
                     const input = call.length > 1 ? call[0] : {};
                     if (extra.requestId === undefined || extra.requestId === null || String(extra.requestId).trim() === "") {

package/dist/mcp/server/tools/messages/wait-tool.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { getPollTimeoutCapMs } from "../../../../shared/poll-timeout-cap.js";
 import { encodeRoomIdPath } from "../../../room-id.js";
 import { agentSessionCredentials, AGENT_MESSAGE_BODY_MAX_BYTES, appendIncludePromptOnly, boundAgentMessageOutput, buildAgentDeliveryHeaders, bindSupervisedWorkerSession, scheduleSupervisedWorkerCursorCheckpoint, currentRoom, ensureAgentIdentity, getFallbackProjectId, getLatestLocalChatMessages, getLocalImportedRoutingAuthority, getLocalChatMessages, getLocalChatThreadRoutingMembership, getLastMessageId, getRememberedRoomPresence, getStoredAgentRoutingStateSnapshot, getTargetRoomId, identityFromAgentSession, isLocalRoomStorageEnabled, listLocalActiveTaskOwnerLeases, resolveLocalRoomStorageIdentifiers, resolveAgentSession, roomScopedApiCall, syncRoomPresence, toAgentReadableMessages, touchRoomSession, WORKER_BEARER_AGENT_SESSION_ID, waitForLocalChatMessages, } from "../../runtime.js";
-import { requireValidWorkerBearerRuntime, supervisedBoundedDeliveryDisabledToolResult, } from "../../runtime/worker-bearer.js";
+import { requireValidWorkerBearerRuntime, isCustodialPolling, supervisedBoundedDeliveryDisabledToolResult, } from "../../runtime/worker-bearer.js";
+import { resolveWorkerToolIdentity } from "../../runtime/agent-sessions.js";
 import { attachAgentMessageActivations, createGlobalAgentAddressResolver, decideAgentMessageActivation, isTaskOwnerFollowUpMessageText, } from "../../../../shared/activation-routing.js";
 import { normalizeRoutingSender } from "../../../../../shared/routing-aliases.mjs";
 import { findLocalMessageById, findRemoteMessageById } from "./message-lookup.js";
@@ -462,14 +463,20 @@ export function registerWaitForMessagesTool(server) {
         const targetProjectId = getFallbackProjectId();
         const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
         const sessionRoomId = targetRoomId ?? currentRoom?.room_id ?? localRoomId ?? null;
-        const routingStateSnapshot = getStoredAgentRoutingStateSnapshot(sessionRoomId ?? "");
+        const custodial = isCustodialPolling();
+        const routingStateSnapshot = custodial ? { complete: true } : getStoredAgentRoutingStateSnapshot(sessionRoomId ?? "");
         const localStorageEnabled = Boolean(localRoomId && await isLocalRoomStorageEnabled(localRoomId));
         if (localStorageEnabled && !routingStateSnapshot.complete) {
             throw new Error("Local agent routing state is unavailable; retry after restoring the state file.");
         }
-        const identity = await ensureAgentIdentity();
-        const agentSession = resolveWaitAgentSession(sessionRoomId, agent_session_id);
-        if (agentSession) {
+        const exactIdentity = custodial ? await resolveWorkerToolIdentity({ roomId: sessionRoomId, agentSessionId: agent_session_id }) : null;
+        const identity = exactIdentity?.identity ?? await ensureAgentIdentity();
+        const agentSession = exactIdentity?.agentSession ?? resolveWaitAgentSession(sessionRoomId, agent_session_id);
+        if (custodial) {
+            if (!agentSession || !after_message_id)
+                throw new Error("Custodial polling requires exact worker identity and durable cursor.");
+        }
+        else if (agentSession) {
             // Registration (or a successor generation) must bind strictly once.
             // Later waits use a read-only exact verification capped at 250ms, so a
             // wedged daemon cannot consume the room-poll budget and an old worker
@@ -570,6 +577,7 @@ export function registerWaitForMessagesTool(server) {
                 project_id: targetProjectId,
                 room_path: (targetRoomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(targetRoomId)}/messages/poll?${queryString}`),
                 project_path: (targetProjectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(targetProjectId)}/messages/poll?${queryString}`),
+                preserve_session_cursor: true,
                 options: buildWaitForMessagesRequestOptions({
                     deliveryHeaders,
                     signal: AbortSignal.timeout(clientTimeout),
@@ -633,12 +641,14 @@ export function registerWaitForMessagesTool(server) {
         if (bounded.omittedMessageCount > 0) {
             output.omitted_message_count = bounded.omittedMessageCount;
         }
-        if (apiObservedCursor)
-            output.last_observed_message_id = apiObservedCursor;
+        // The API cursor can cover concealed messages, but not visible messages
+        // omitted by our own byte bound. Resume after the retained page instead.
+        const observedCursor = !bounded.truncated && apiObservedCursor
+            ? apiObservedCursor
+            : routing.last_observed_message_id ?? undefined;
+        if (observedCursor)
+            output.last_observed_message_id = observedCursor;
         if (targetRoomId) {
-            const observedCursor = apiObservedCursor
-                ?? routing.last_observed_message_id
-                ?? getLastMessageId(output);
             touchRoomSession(targetRoomId, observedCursor);
             if (allMessages.length > 0 && agentSession) {
                 const firstMsg = allMessages[0];

package/dist/shared/activation-routing.js

@@ -312,7 +312,7 @@ export function resolveGloballyAddressedAgentKeys(message, identities) {
  * 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) {
+export function createGlobalAgentAddressResolver(identities, options = {}) {
     const keysByAlias = new Map();
     for (const identity of identities) {
         const key = normalizedString(identity.agent_key);
@@ -324,6 +324,23 @@ export function createGlobalAgentAddressResolver(identities) {
             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);
@@ -336,9 +353,9 @@ export function createGlobalAgentAddressResolver(identities) {
             const alias = normalizeMentionIdentityHandle(mention);
             if (!alias)
                 continue;
-            const keys = keysByAlias.get(alias);
-            if (keys?.size === 1)
-                explicitMentionKeys.add(keys.values().next().value);
+            const resolvedKey = resolveExplicitMentionKey(keysByAlias.get(alias));
+            if (resolvedKey)
+                explicitMentionKeys.add(resolvedKey);
         }
         const replyTargetKeys = new Set();
         const replyAliases = normalizedString(message.reply_to?.source) === "agent"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.13",
+  "version": "0.12.14",
   "description": "Let Agents Chat — MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",
@@ -26,7 +26,7 @@
     "test:web": "node --import tsx --test src/web/tests/*.test.ts src/web/src/composables/*.test.ts",
     "test:dependency-age": "node --test scripts/verify-dependency-age.test.mjs",
     "test:docker-context": "node --test scripts/verify-docker-context.test.mjs",
-    "test:workflow-supply-chain": "node --test scripts/verify-workflow-supply-chain.test.mjs",
+    "test:workflow-supply-chain": "node --test scripts/verify-workflow-supply-chain.test.mjs scripts/verify-dependency-advisories.test.mjs",
     "test:notifications": "node --import tsx --test src/api/notifications/__tests__/*.test.ts",
     "verify:dependency-age": "node scripts/verify-dependency-age.mjs",
     "db:generate": "drizzle-kit generate",
@@ -70,7 +70,7 @@
     "@esbuild-kit/core-utils": {
       "esbuild": "^0.25.12"
     },
-    "fast-uri": "3.1.5",
+    "fast-uri": "3.1.6",
     "hono": "4.12.34",
     "ip-address": "10.3.1"
   }

package/shared/execution-approval-projection.d.mts

@@ -0,0 +1,32 @@
+export const EXECUTION_APPROVAL_PROJECTION_VERSION: 1;
+export const EXECUTION_APPROVAL_PROJECTION_MAX_FILES: 128;
+export const EXECUTION_APPROVAL_PROJECTION_MAX_PATH_BYTES: 4096;
+export const EXECUTION_APPROVAL_PROJECTION_MAX_BYTES: number;
+
+export type ExecutionApprovalProjectionChangeKind = "add" | "delete" | "update" | "move";
+export type ExecutionApprovalProjectionChange = {
+  path: string;
+  kind: ExecutionApprovalProjectionChangeKind;
+  move_path: string | null;
+  added_lines: number;
+  removed_lines: number;
+  diff_bytes: number;
+};
+export type ExecutionApprovalProjectionV1 = {
+  version: 1;
+  category: "file_change";
+  path_scope: "workspace_relative";
+  changes: ExecutionApprovalProjectionChange[];
+  totals: {
+    file_count: number;
+    added_lines: number;
+    removed_lines: number;
+    diff_bytes: number;
+  };
+};
+
+export function isExecutionApprovalProjectionPath(value: unknown): value is string;
+/** Return the canonical allowlisted projection, or reject it as a whole. */
+export function parseExecutionApprovalProjectionV1(value: unknown): ExecutionApprovalProjectionV1 | null;
+/** Serialize only the canonical, bounded bytes that a delegate may see. */
+export function serializeExecutionApprovalProjectionV1(value: unknown): string | null;

package/shared/execution-approval-projection.mjs

@@ -0,0 +1,107 @@
+export const EXECUTION_APPROVAL_PROJECTION_VERSION = 1;
+export const EXECUTION_APPROVAL_PROJECTION_MAX_FILES = 128;
+export const EXECUTION_APPROVAL_PROJECTION_MAX_PATH_BYTES = 4096;
+export const EXECUTION_APPROVAL_PROJECTION_MAX_BYTES = 24 * 1024;
+
+const ROOT_KEYS = ["version", "category", "path_scope", "changes", "totals"];
+const CHANGE_KEYS = ["path", "kind", "move_path", "added_lines", "removed_lines", "diff_bytes"];
+const TOTAL_KEYS = ["file_count", "added_lines", "removed_lines", "diff_bytes"];
+const CHANGE_KINDS = ["add", "delete", "update", "move"];
+const UNSAFE_PATH_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function count(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+export function isExecutionApprovalProjectionPath(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.normalize("NFC") === value
+    && new TextEncoder().encode(value).byteLength <= EXECUTION_APPROVAL_PROJECTION_MAX_PATH_BYTES
+    && !value.startsWith("/")
+    && !value.includes("\\")
+    && !UNSAFE_PATH_CHARACTERS.test(value)
+    && value.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+
+function compareChanges(left, right) {
+  for (const [a, b] of [[left.path, right.path], [left.kind, right.kind], [left.move_path ?? "", right.move_path ?? ""]]) {
+    if (a < b) return -1;
+    if (a > b) return 1;
+  }
+  return 0;
+}
+
+/** Return the canonical allowlisted projection, or reject it as a whole. */
+export function parseExecutionApprovalProjectionV1(value) {
+  if (!exactKeys(value, ROOT_KEYS)
+    || value.version !== EXECUTION_APPROVAL_PROJECTION_VERSION
+    || value.category !== "file_change"
+    || value.path_scope !== "workspace_relative"
+    || !Array.isArray(value.changes)
+    || value.changes.length < 1
+    || value.changes.length > EXECUTION_APPROVAL_PROJECTION_MAX_FILES
+    || !exactKeys(value.totals, TOTAL_KEYS)) return null;
+
+  const changes = [];
+  for (const candidate of value.changes) {
+    if (!exactKeys(candidate, CHANGE_KEYS)
+      || !isExecutionApprovalProjectionPath(candidate.path)
+      || !CHANGE_KINDS.includes(candidate.kind)
+      || !count(candidate.added_lines)
+      || !count(candidate.removed_lines)
+      || !count(candidate.diff_bytes)
+      || (candidate.kind === "move") !== (candidate.move_path !== null)
+      || (candidate.move_path !== null && !isExecutionApprovalProjectionPath(candidate.move_path))) return null;
+    changes.push({
+      path: candidate.path,
+      kind: candidate.kind,
+      move_path: candidate.move_path,
+      added_lines: candidate.added_lines,
+      removed_lines: candidate.removed_lines,
+      diff_bytes: candidate.diff_bytes,
+    });
+  }
+  changes.sort(compareChanges);
+  const occupied = new Set();
+  for (const change of changes) {
+    if (occupied.has(change.path)) return null;
+    occupied.add(change.path);
+    if (change.move_path !== null) {
+      if (occupied.has(change.move_path)) return null;
+      occupied.add(change.move_path);
+    }
+  }
+  const totals = changes.reduce((result, change) => ({
+    file_count: result.file_count + 1,
+    added_lines: result.added_lines + change.added_lines,
+    removed_lines: result.removed_lines + change.removed_lines,
+    diff_bytes: result.diff_bytes + change.diff_bytes,
+  }), { file_count: 0, added_lines: 0, removed_lines: 0, diff_bytes: 0 });
+  if (!Object.values(totals).every(Number.isSafeInteger)
+    || TOTAL_KEYS.some((key) => value.totals[key] !== totals[key])) return null;
+
+  return {
+    version: EXECUTION_APPROVAL_PROJECTION_VERSION,
+    category: "file_change",
+    path_scope: "workspace_relative",
+    changes,
+    totals,
+  };
+}
+
+/** Serialize only the canonical, bounded bytes that a delegate may see. */
+export function serializeExecutionApprovalProjectionV1(value) {
+  const parsed = parseExecutionApprovalProjectionV1(value);
+  if (!parsed) return null;
+  const serialized = JSON.stringify(parsed);
+  return new TextEncoder().encode(serialized).byteLength <= EXECUTION_APPROVAL_PROJECTION_MAX_BYTES
+    ? serialized
+    : null;
+}

package/shared/execution-approval-publication-item.d.mts

@@ -0,0 +1,20 @@
+export type ExecutionApprovalPublicationItem = {
+  publication_id: string;
+  room_id: string;
+  agent_key: string;
+  delegation_instance_id: string;
+  delegation_revision: number;
+  request_id: string;
+  request_version: number;
+  request_sha256: string;
+  projection_sha256: string;
+  published_at: string;
+  expires_at: string;
+};
+
+export function isExecutionApprovalPublicationIdentity(value: unknown): value is string;
+export function isExecutionApprovalPublicationDigest(value: unknown): value is string;
+export function isExecutionApprovalPublicationVersion(value: unknown): value is number;
+export function parseExecutionApprovalPublicationItem(
+  value: unknown,
+): ExecutionApprovalPublicationItem | null;

package/shared/execution-approval-publication-item.mjs

@@ -0,0 +1,61 @@
+const ITEM_KEYS = [
+  "publication_id",
+  "room_id",
+  "agent_key",
+  "delegation_instance_id",
+  "delegation_revision",
+  "request_id",
+  "request_version",
+  "request_sha256",
+  "projection_sha256",
+  "published_at",
+  "expires_at",
+];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+export function isExecutionApprovalPublicationIdentity(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= 512
+    && value.trim() === value
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+export function isExecutionApprovalPublicationDigest(value) {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function isExecutionApprovalPublicationVersion(value) {
+  return Number.isSafeInteger(value) && value >= 1 && value <= 2_147_483_647;
+}
+
+function canonicalTimestamp(value) {
+  if (typeof value !== "string") return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value
+    ? timestamp
+    : null;
+}
+
+/** Parse the exact public inventory item shared by the API and browser. */
+export function parseExecutionApprovalPublicationItem(value) {
+  if (!exactKeys(value, ITEM_KEYS)
+    || !isExecutionApprovalPublicationIdentity(value.publication_id)
+    || !isExecutionApprovalPublicationIdentity(value.room_id)
+    || !isExecutionApprovalPublicationIdentity(value.agent_key)
+    || !isExecutionApprovalPublicationIdentity(value.delegation_instance_id)
+    || !isExecutionApprovalPublicationVersion(value.delegation_revision)
+    || !isExecutionApprovalPublicationIdentity(value.request_id)
+    || !isExecutionApprovalPublicationVersion(value.request_version)
+    || !isExecutionApprovalPublicationDigest(value.request_sha256)
+    || !isExecutionApprovalPublicationDigest(value.projection_sha256)) return null;
+  const publishedAt = canonicalTimestamp(value.published_at);
+  const expiresAt = canonicalTimestamp(value.expires_at);
+  if (publishedAt === null || expiresAt === null || expiresAt <= publishedAt) return null;
+  return Object.fromEntries(ITEM_KEYS.map((key) => [key, value[key]]));
+}

package/shared/execution-approval-publication.d.mts

@@ -0,0 +1,53 @@
+import type { ExecutionApprovalProjectionV1 } from "./execution-approval-projection.mjs";
+import type { ExecutionApprovalPublicationItem } from "./execution-approval-publication-item.mjs";
+
+export {
+  isExecutionApprovalPublicationDigest,
+  isExecutionApprovalPublicationIdentity,
+  isExecutionApprovalPublicationVersion,
+  parseExecutionApprovalPublicationItem,
+} from "./execution-approval-publication-item.mjs";
+export type { ExecutionApprovalPublicationItem } from "./execution-approval-publication-item.mjs";
+
+export const EXECUTION_APPROVAL_PUBLICATION_VERSION: 1;
+export const EXECUTION_APPROVAL_PUBLICATION_MAX_JSON_BYTES: number;
+
+export type ExecutionApprovalPublicationInput = {
+  version: 1;
+  room_id: string;
+  source_message_id: string;
+  delegation_instance_id: string;
+  delegation_revision: number;
+  request_id: string;
+  request_version: number;
+  request_sha256: string;
+  projection_sha256: string;
+  projection_json: string;
+  produced_at: string;
+  expires_at: string;
+};
+
+export type ExecutionApprovalPublicationReceipt = {
+  status: "created" | "replayed";
+  publication_digest: string;
+  publication: ExecutionApprovalPublicationItem;
+};
+
+export type ExecutionApprovalPublicationCloseInput = {
+  publication_digest: string;
+};
+
+export type ExecutionApprovalPublicationCloseReceipt = {
+  status: "closed" | "replayed";
+  publication_id: string;
+  publication_digest: string;
+  closed_at: string;
+};
+
+export function parseExecutionApprovalPublicationInput(value: unknown): ExecutionApprovalPublicationInput | null;
+export function parseExecutionApprovalPublicationReceipt(value: unknown): ExecutionApprovalPublicationReceipt | null;
+export function parseExecutionApprovalPublicationCloseInput(value: unknown): ExecutionApprovalPublicationCloseInput | null;
+export function parseExecutionApprovalPublicationCloseReceipt(value: unknown): ExecutionApprovalPublicationCloseReceipt | null;
+export function executionApprovalPublicationSha256(value: unknown): string | null;
+
+export type { ExecutionApprovalProjectionV1 };

package/shared/execution-approval-publication.mjs

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+
+import {
+  parseExecutionApprovalProjectionV1,
+  serializeExecutionApprovalProjectionV1,
+} from "./execution-approval-projection.mjs";
+import {
+  isExecutionApprovalPublicationDigest,
+  isExecutionApprovalPublicationIdentity,
+  isExecutionApprovalPublicationVersion,
+  parseExecutionApprovalPublicationItem,
+} from "./execution-approval-publication-item.mjs";
+
+export {
+  isExecutionApprovalPublicationDigest,
+  isExecutionApprovalPublicationIdentity,
+  isExecutionApprovalPublicationVersion,
+  parseExecutionApprovalPublicationItem,
+} from "./execution-approval-publication-item.mjs";
+
+export const EXECUTION_APPROVAL_PUBLICATION_VERSION = 1;
+export const EXECUTION_APPROVAL_PUBLICATION_MAX_JSON_BYTES = 24 * 1024;
+
+const INPUT_KEYS = [
+  "version",
+  "room_id",
+  "source_message_id",
+  "delegation_instance_id",
+  "delegation_revision",
+  "request_id",
+  "request_version",
+  "request_sha256",
+  "projection_sha256",
+  "projection_json",
+  "produced_at",
+  "expires_at",
+];
+const RECEIPT_KEYS = ["status", "publication_digest", "publication"];
+const CLOSE_INPUT_KEYS = ["publication_digest"];
+const CLOSE_RECEIPT_KEYS = ["status", "publication_id", "publication_digest", "closed_at"];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function canonicalTimestamp(value) {
+  if (typeof value !== "string") return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value
+    ? timestamp
+    : null;
+}
+
+function sourceMessage(value) {
+  return typeof value === "string"
+    && /^msg_[1-9]\d{0,9}$/.test(value)
+    && Number(value.slice(4)) <= 2_147_483_647;
+}
+
+function canonicalProjection(value) {
+  if (typeof value !== "string"
+    || new TextEncoder().encode(value).byteLength > EXECUTION_APPROVAL_PUBLICATION_MAX_JSON_BYTES) return false;
+  let parsed;
+  try { parsed = JSON.parse(value); } catch { return false; }
+  const projection = parseExecutionApprovalProjectionV1(parsed);
+  return projection !== null && serializeExecutionApprovalProjectionV1(projection) === value;
+}
+
+/** Parse exact daemon-to-server publication bytes; digest verification remains the receiver's job. */
+export function parseExecutionApprovalPublicationInput(value) {
+  if (!exactKeys(value, INPUT_KEYS)
+    || value.version !== EXECUTION_APPROVAL_PUBLICATION_VERSION
+    || !isExecutionApprovalPublicationIdentity(value.room_id)
+    || !sourceMessage(value.source_message_id)
+    || !isExecutionApprovalPublicationIdentity(value.delegation_instance_id)
+    || !isExecutionApprovalPublicationVersion(value.delegation_revision)
+    || !isExecutionApprovalPublicationIdentity(value.request_id)
+    || !isExecutionApprovalPublicationVersion(value.request_version)
+    || !isExecutionApprovalPublicationDigest(value.request_sha256)
+    || !isExecutionApprovalPublicationDigest(value.projection_sha256)
+    || !canonicalProjection(value.projection_json)) return null;
+  const producedAt = canonicalTimestamp(value.produced_at);
+  const expiresAt = canonicalTimestamp(value.expires_at);
+  if (producedAt === null || expiresAt === null || expiresAt <= producedAt) return null;
+  return Object.fromEntries(INPUT_KEYS.map((key) => [key, value[key]]));
+}
+
+export function parseExecutionApprovalPublicationReceipt(value) {
+  if (!exactKeys(value, RECEIPT_KEYS)
+    || !["created", "replayed"].includes(value.status)
+    || !isExecutionApprovalPublicationDigest(value.publication_digest)) return null;
+  const publication = parseExecutionApprovalPublicationItem(value.publication);
+  return publication ? {
+    status: value.status,
+    publication_digest: value.publication_digest,
+    publication,
+  } : null;
+}
+
+/** Parse the content-free host acknowledgement that a publication is no longer actionable. */
+export function parseExecutionApprovalPublicationCloseInput(value) {
+  return exactKeys(value, CLOSE_INPUT_KEYS)
+    && isExecutionApprovalPublicationDigest(value.publication_digest)
+    ? { publication_digest: value.publication_digest }
+    : null;
+}
+
+export function parseExecutionApprovalPublicationCloseReceipt(value) {
+  if (!exactKeys(value, CLOSE_RECEIPT_KEYS)
+    || !["closed", "replayed"].includes(value.status)
+    || !isExecutionApprovalPublicationIdentity(value.publication_id)
+    || !isExecutionApprovalPublicationDigest(value.publication_digest)
+    || canonicalTimestamp(value.closed_at) === null) return null;
+  return Object.fromEntries(CLOSE_RECEIPT_KEYS.map((key) => [key, value[key]]));
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** Digest exact, validated publication input with the server's stable-key wire algorithm. */
+export function executionApprovalPublicationSha256(value) {
+  const publication = parseExecutionApprovalPublicationInput(value);
+  return publication === null
+    ? null
+    : createHash("sha256").update(stableJson(publication), "utf8").digest("hex");
+}

package/shared/execution-delegation-decision.d.mts

@@ -0,0 +1,37 @@
+export const EXECUTION_DELEGATION_DECISIONS: readonly ["allow_once", "deny"];
+export const EXECUTION_DELEGATION_DECISION_APPLICABILITY_MS: number;
+
+export type ExecutionDelegationDecisionChoice =
+  typeof EXECUTION_DELEGATION_DECISIONS[number];
+
+export function isExecutionDelegationDecision(
+  value: unknown,
+): value is ExecutionDelegationDecisionChoice;
+export function isExecutionDelegationIdentity(value: unknown): value is string;
+export function isExecutionDelegationDigest(value: unknown): value is string;
+export function isExecutionDelegationPositiveInt32(value: unknown): value is number;
+
+export type ExecutionDelegationDecisionIntent = {
+  decision_id: string;
+  delegation_instance_id: string;
+  delegation_revision: number;
+  actor_account_id: string;
+  request_id: string;
+  request_version: number;
+  request_sha256: string;
+  projection_sha256: string;
+  decision: ExecutionDelegationDecisionChoice;
+  decided_at: string;
+  owner_account_id: string;
+  room_id: string;
+  agent_key: string;
+  approver_account_id: string;
+  category: "file_change";
+  risk_ceiling: "low";
+  scope_sha256: string;
+};
+
+/** Return the exact host-delivered decision intent, or reject it as a whole. */
+export function parseExecutionDelegationDecisionIntent(
+  value: unknown,
+): ExecutionDelegationDecisionIntent | null;

package/shared/execution-delegation-decision.mjs

@@ -0,0 +1,73 @@
+export const EXECUTION_DELEGATION_DECISIONS = ["allow_once", "deny"];
+export const EXECUTION_DELEGATION_DECISION_APPLICABILITY_MS = 24 * 60 * 60 * 1000;
+
+export function isExecutionDelegationDecision(value) {
+  return EXECUTION_DELEGATION_DECISIONS.includes(value);
+}
+
+const INTENT_KEYS = [
+  "decision_id",
+  "delegation_instance_id",
+  "delegation_revision",
+  "actor_account_id",
+  "request_id",
+  "request_version",
+  "request_sha256",
+  "projection_sha256",
+  "decision",
+  "decided_at",
+  "owner_account_id",
+  "room_id",
+  "agent_key",
+  "approver_account_id",
+  "category",
+  "risk_ceiling",
+  "scope_sha256",
+];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+export function isExecutionDelegationIdentity(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= 512
+    && value.trim() === value
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+export function isExecutionDelegationDigest(value) {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function isExecutionDelegationPositiveInt32(value) {
+  return Number.isSafeInteger(value) && value >= 1 && value <= 2_147_483_647;
+}
+
+/** Return the exact host-delivered decision intent, or reject it as a whole. */
+export function parseExecutionDelegationDecisionIntent(value) {
+  if (!exactKeys(value, INTENT_KEYS)
+    || !isExecutionDelegationIdentity(value.decision_id)
+    || !isExecutionDelegationIdentity(value.delegation_instance_id)
+    || !isExecutionDelegationPositiveInt32(value.delegation_revision)
+    || !isExecutionDelegationIdentity(value.actor_account_id)
+    || !isExecutionDelegationIdentity(value.request_id)
+    || !isExecutionDelegationPositiveInt32(value.request_version)
+    || !isExecutionDelegationDigest(value.request_sha256)
+    || !isExecutionDelegationDigest(value.projection_sha256)
+    || !isExecutionDelegationDecision(value.decision)
+    || typeof value.decided_at !== "string" || !Number.isFinite(Date.parse(value.decided_at))
+    || !isExecutionDelegationIdentity(value.owner_account_id)
+    || !isExecutionDelegationIdentity(value.room_id)
+    || !isExecutionDelegationIdentity(value.agent_key)
+    || !isExecutionDelegationIdentity(value.approver_account_id)
+    || value.actor_account_id !== value.approver_account_id
+    || value.category !== "file_change"
+    || value.risk_ceiling !== "low"
+    || !isExecutionDelegationDigest(value.scope_sha256)) return null;
+
+  return Object.fromEntries(INTENT_KEYS.map((key) => [key, value[key]]));
+}

package/shared/room-agent-work.d.mts

@@ -0,0 +1,31 @@
+export const ROOM_WORK_STATES: readonly ["active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown"];
+export const ROOM_WORK_OPERATION_OUTCOMES: readonly ["unresolved", "succeeded", "failed", "denied_before_start", "cancelled_before_start", "interrupted_after_start", "lost_after_start"];
+export type RoomAgentWorkSummary = {
+  version: 1;
+  recorded_state: typeof ROOM_WORK_STATES[number];
+  evidence_incomplete: boolean;
+  elapsed_ms: number | null;
+  operation_counts: Record<typeof ROOM_WORK_OPERATION_OUTCOMES[number], number>;
+};
+// Server-issued availability marker, not a publisher-supplied execution state.
+export type ClearedRoomAgentWorkSummary = { version: 1; availability: "cleared" };
+export type RoomAgentWork = {
+  attempt_id: string;
+  room_id: string;
+  source_message_id: string;
+  agent_key: string;
+  revision: number;
+  summary: RoomAgentWorkSummary | ClearedRoomAgentWorkSummary;
+  updated_at: string;
+};
+export type RoomAgentWorkSnapshot = { work: RoomAgentWork[]; truncated: boolean };
+/** Synchronizes the latest-50 view, not intermediate events or complete history.
+ * A changed snapshot replaces the client's bounded cache; it must not be merged.
+ * The server-issued cursor is a comparison hint, never authorization. */
+export type RoomAgentWorkPollResponse = { room_id: string; cursor: string } & (
+  | { changed: true; snapshot: RoomAgentWorkSnapshot }
+  | { changed: false; snapshot: null }
+);
+export function isClearedRoomAgentWorkSummary(value: unknown): value is ClearedRoomAgentWorkSummary;
+/** Return a canonical allowlisted copy, or reject without echoing private input. */
+export function parseRoomAgentWorkSummary(value: unknown): RoomAgentWorkSummary | null;

package/shared/room-agent-work.mjs

@@ -0,0 +1,44 @@
+// Room-public, host-reported evidence; never execution or approval authority.
+// No free-form strings, native handles, paths, command text, or output belong
+// in this version. Both the publisher and server use this strict boundary.
+export const ROOM_WORK_STATES = [
+  "active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown",
+];
+export const ROOM_WORK_OPERATION_OUTCOMES = [
+  "unresolved", "succeeded", "failed", "denied_before_start", "cancelled_before_start",
+  "interrupted_after_start", "lost_after_start",
+];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+export function isClearedRoomAgentWorkSummary(value) {
+  return exactKeys(value, ["version", "availability"]) && value.version === 1 && value.availability === "cleared";
+}
+
+/** Return a canonical allowlisted copy, or reject without echoing private input. */
+export function parseRoomAgentWorkSummary(value) {
+  if (!exactKeys(value, ["version", "recorded_state", "evidence_incomplete", "elapsed_ms", "operation_counts"])
+    || value.version !== 1 || !ROOM_WORK_STATES.includes(value.recorded_state)
+    || typeof value.evidence_incomplete !== "boolean"
+    || (value.elapsed_ms !== null && (!Number.isSafeInteger(value.elapsed_ms) || Number(value.elapsed_ms) < 0))
+    || !exactKeys(value.operation_counts, ROOM_WORK_OPERATION_OUTCOMES)) return null;
+  const counts = {};
+  let total = 0;
+  for (const outcome of ROOM_WORK_OPERATION_OUTCOMES) {
+    const count = value.operation_counts[outcome];
+    if (!Number.isSafeInteger(count) || Number(count) < 0) return null;
+    counts[outcome] = Number(count);
+    total += Number(count);
+  }
+  // A bounded evidence snapshot, not an unbounded lifetime counter.
+  if (total > 10_000) return null;
+  return {
+    version: 1, recorded_state: value.recorded_state,
+    evidence_incomplete: value.evidence_incomplete, elapsed_ms: value.elapsed_ms,
+    operation_counts: counts,
+  };
+}

package/shared/room-resource-invalidation.d.mts

@@ -0,0 +1,38 @@
+export const ROOM_RESOURCE_INVALIDATION_CAPABILITY: "resource_invalidation_v1";
+export const ROOM_RESOURCE_AGENT_WORK: "agent_work";
+/** Content-free approval-state hint; consumers repair through separately authorized exact reads. */
+export const ROOM_RESOURCE_AGENT_APPROVAL: "agent_approval";
+export const ROOM_RESOURCE_EXECUTION_DELEGATION: "execution_delegation";
+/** Protocol-known references; consumers independently choose what they render. */
+export const ROOM_RESOURCE_INVALIDATION_RESOURCES: readonly [
+  "agent_work",
+  "agent_approval",
+  "execution_delegation",
+];
+
+export type RoomResourceInvalidationResource =
+  typeof ROOM_RESOURCE_INVALIDATION_RESOURCES[number];
+
+export type RoomResourceInvalidationPointer<Resource extends string = string> = {
+  room_id: string;
+  resource: Resource;
+};
+
+export type RoomResourceInvalidationParseResult =
+  | {
+      status: "supported";
+      pointer: RoomResourceInvalidationPointer<RoomResourceInvalidationResource>;
+    }
+  | {
+      status: "unsupported";
+      pointer: RoomResourceInvalidationPointer;
+    }
+  | { status: "malformed" };
+
+/**
+ * Parse a bounded room-resource pointer without echoing malformed input.
+ * Unknown but well-formed resources remain forward-compatible cursor no-ops.
+ */
+export function parseRoomResourceInvalidation(
+  value: unknown,
+): RoomResourceInvalidationParseResult;

package/shared/room-resource-invalidation.mjs

@@ -0,0 +1,50 @@
+export const ROOM_RESOURCE_INVALIDATION_CAPABILITY = "resource_invalidation_v1";
+export const ROOM_RESOURCE_AGENT_WORK = "agent_work";
+// Content-free hint emitted when an approval projection is published or its
+// decision-relevant room state changes. Consumers repair through separately
+// authorized exact reads; the pointer never carries approval content.
+export const ROOM_RESOURCE_AGENT_APPROVAL = "agent_approval";
+export const ROOM_RESOURCE_EXECUTION_DELEGATION = "execution_delegation";
+// Protocol-known references. Each consumer still decides which surfaces, if
+// any, react to a supported pointer.
+export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
+  ROOM_RESOURCE_AGENT_WORK,
+  ROOM_RESOURCE_AGENT_APPROVAL,
+  ROOM_RESOURCE_EXECUTION_DELEGATION,
+];
+
+function exactKeys(value, keys) {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function isValidRoomIdentifier(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= 512
+    && value.trim() === value
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function isValidResource(value) {
+  return typeof value === "string"
+    && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(value);
+}
+
+/**
+ * Parse a bounded room-resource pointer without echoing malformed input.
+ * Unknown but well-formed resources remain forward-compatible cursor no-ops.
+ */
+export function parseRoomResourceInvalidation(value) {
+  if (
+    !exactKeys(value, ["room_id", "resource"])
+    || !isValidRoomIdentifier(value.room_id)
+    || !isValidResource(value.resource)
+  ) return { status: "malformed" };
+
+  const pointer = { room_id: value.room_id, resource: value.resource };
+  return ROOM_RESOURCE_INVALIDATION_RESOURCES.includes(value.resource)
+    ? { status: "supported", pointer }
+    : { status: "unsupported", pointer };
+}