sentinelayer-cli 0.39.2 → 0.41.0

package/src/engram/trust.js

@@ -0,0 +1,105 @@
+/**
+ * ENGRAM §2 — the trust seal on write.
+ *
+ * Vocabulary is DELIBERATELY aligned with the server-side `ServiceTrustLevel`
+ * subsystem (sentinelayer-api `src/models/service_trust.py`: L0_connected ->
+ * L5_remediation_ready) so §2.1 converges onto that existing certification
+ * system instead of forking a divergent trust model. P0 stays CLI-local and
+ * does NOT touch the server subsystem — it only borrows the vocabulary.
+ *
+ * Rule (from the convergence + guest-token model): only VERIFIED writes are
+ * AUTHORITATIVE; untrusted/guest/unverified writes are retrievable-but-marked,
+ * never authoritative, never a governed-action trigger. `sealed`/`revoked`
+ * memories are never surfaced to an unauthorized scope (the §10 analog).
+ *
+ * Real verification (AIdenID provider-signature / delegation-proof) is
+ * external (§2.1); P0 classifies from local identity signals.
+ */
+
+export const TRUST_LEVELS = Object.freeze([
+  "L0_connected",
+  "L1_audited",
+  "L2_memory_certified",
+  "L3_watch_enabled",
+  "L4_governance_grade",
+  "L5_remediation_ready",
+]);
+
+const RANK = new Map(TRUST_LEVELS.map((level, index) => [level, index]));
+
+/** Writes at or above this level are AUTHORITATIVE. */
+export const AUTHORITATIVE_FLOOR = "L2_memory_certified";
+
+export function trustRank(level) {
+  return RANK.has(level) ? RANK.get(level) : 0;
+}
+
+export function isAuthoritative(level) {
+  return trustRank(level) >= trustRank(AUTHORITATIVE_FLOOR);
+}
+
+/**
+ * Classify a write's trust level from the caller. AIdenID verification is
+ * external (§2.1); until then a caller is authoritative only if it presents a
+ * verified identity.
+ * @param {object} [caller]  { id, kind?, verified?, trustLevel? }
+ * @returns {string} a TRUST_LEVELS value
+ */
+export function classifyWrite(caller = {}) {
+  if (!caller || !caller.id || caller.kind === "guest") return "L0_connected";
+  if (caller.verified === true) {
+    return caller.trustLevel && RANK.has(caller.trustLevel) ? caller.trustLevel : "L2_memory_certified";
+  }
+  return "L1_audited"; // known but unverified -> retrievable, NOT authoritative
+}
+
+/**
+ * Classify a source-adapter observation (e.g. a session event) from its
+ * author when the item carried no explicit trust.
+ * @param {object} obs
+ * @returns {string}
+ */
+export function classifyObservation(obs = {}) {
+  const agentId = String(obs.agentId || "").toLowerCase();
+  if (!agentId || agentId === "unknown" || agentId === "cli-user" || agentId.startsWith("guest") || agentId.startsWith("agent-")) {
+    return "L0_connected";
+  }
+  return "L1_audited";
+}
+
+/**
+ * Attach the trust seal to an item at write time.
+ * @param {object} item
+ * @param {object} ctx  { caller }
+ * @returns {object} item with { trust, sealed, revoked }
+ */
+export function sealItem(item, { caller } = {}) {
+  // Trust is DERIVED from the caller's identity, never self-asserted. A caller
+  // MAY downgrade their own write (mark it less trusted); they may NEVER upgrade
+  // above their identity-derived ceiling — otherwise an unverified/guest caller
+  // could forge an AUTHORITATIVE memory by supplying `trust` in the payload,
+  // defeating the "unverified -> never authoritative" invariant above.
+  const derived = classifyWrite(caller);
+  const asserted = item?.trust && RANK.has(item.trust) ? item.trust : derived;
+  const trust = trustRank(asserted) <= trustRank(derived) ? asserted : derived;
+  return {
+    ...item,
+    trust,
+    sealed: item?.sealed === true,
+    revoked: item?.revoked === true,
+  };
+}
+
+/**
+ * Recall visibility gate: revoked memory NEVER surfaces; sealed memory
+ * surfaces only to an authorized scope. Untrusted memory DOES surface (marked
+ * non-authoritative by the caller).
+ * @param {object} obs
+ * @param {object} [ctx]  { authorized }
+ * @returns {boolean}
+ */
+export function visibleUnderScope(obs, { authorized = false } = {}) {
+  if (obs?.revoked === true) return false;
+  if (obs?.sealed === true && !authorized) return false;
+  return true;
+}

package/src/legacy-cli.js

@@ -216,7 +216,10 @@ function printUsage() {
   console.log("  sl session templates --json        List available session quick-start templates");
   console.log("  sl session join <id> --name <n>    Join a session as an agent");
   console.log("  sl session say <id> \"msg\" --json  Append a message event to session stream");
-  console.log("  sl session say <id> \"lock: <file> - <intent>\"  Request an exclusive file lock via Senti");
+  console.log("  sl session lock <id> <file> --agent <agent> --intent <text>  Claim an API-backed file lease outside chat");
+  console.log("  sl session guard-install <id> --agent <agent>  Install terminal/editor lease preflights");
+  console.log("  sl session guard-uninstall <id> --agent <agent>  Remove managed preflights before CLI rollback");
+  console.log("  sl session unlock <id> <file> --agent <agent>  Release an API-backed file lease");
   console.log("  sl session say <id> \"assign: @agent <task>\"  Create task assignment + lease");
   console.log("  sl session say <id> \"assign: @*:reviewer <task>\"  Wildcard route to least-busy role");
   console.log("  sl session say <id> \"accepted: task <task-id>\" / \"done: task <task-id>\"  Task transitions");
@@ -2517,7 +2520,7 @@ jobs:
           fi
       - name: Run Omar Gate
         id: omar
-        uses: mrrCarter/sentinelayer-v1-action@a496be33a466c0cc3f8616d66bbd7d78f7d3c31d
+        uses: mrrCarter/sentinelayer-v1-action@8afb7dbb42a5e1c25233d422c4cabe401ba02380
         with:
           github_token: \${{ github.token }}
           openai_api_key: \${{ secrets.OPENAI_API_KEY }}
@@ -2626,7 +2629,7 @@ jobs:
               },
               "scan": {
                   "mode": env("OMAR_SCAN_MODE", "deep"),
-                  "action_ref": "mrrCarter/sentinelayer-v1-action@a496be33a466c0cc3f8616d66bbd7d78f7d3c31d",
+                  "action_ref": "mrrCarter/sentinelayer-v1-action@8afb7dbb42a5e1c25233d422c4cabe401ba02380",
                   "llm_provider": env("OMAR_LLM_PROVIDER", "openai"),
                   "model": env("OMAR_MODEL", "gpt-5.3-codex"),
                   "model_fallback": env("OMAR_MODEL_FALLBACK", "gpt-4.1-mini"),

package/src/mcp/registry.js

@@ -525,7 +525,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "poll_inbox",
         title: "Poll Senti Inbox",
         description:
-          "Poll durable SentinelLayer session events after an optional cursor and return events visible to one agent.",
+          "Poll durable SentinelLayer session events after an optional cursor, return events visible to one agent, and advance one monotonic read cursor.",
         input_schema: {
           type: "object",
           additionalProperties: false,
@@ -567,13 +567,14 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "read_history",
         title: "Read Senti History",
         description:
-          "Hydrate a bounded recent, older, or after-cursor SentinelLayer session transcript window without recipient filtering.",
+          "Hydrate a bounded recent, older, or after-cursor SentinelLayer session transcript window and advance one monotonic read cursor without appending view events.",
         input_schema: {
           type: "object",
           additionalProperties: false,
           required: ["sessionId"],
           properties: {
             sessionId: { type: "string" },
+            agentId: { type: "string" },
             cursor: { type: "string" },
             beforeSequence: { type: "integer", minimum: 1 },
             limit: { type: "integer", minimum: 1, maximum: 200 },
@@ -654,7 +655,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "session_action",
         title: "Record Senti Session Action",
         description:
-          "Record a low-noise message action such as ack, working_on, disregard, view, like, dislike, or reply against a target session event.",
+          "Record a low-noise message action such as ack, working_on, disregard, like, dislike, or reply; view advances the monotonic read cursor instead of appending an action.",
         input_schema: {
           type: "object",
           additionalProperties: false,
@@ -787,7 +788,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "session_lock",
         title: "Lock Senti Files",
         description:
-          "Claim session-scoped file locks before editing files, using the same fail-closed lock registry as the CLI.",
+          "Claim session-scoped file leases through the authoritative SentinelLayer API before editing. Lease lifecycle operations never create session events.",
         input_schema: {
           type: "object",
           additionalProperties: false,
@@ -803,8 +804,16 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
             },
             intent: { type: "string" },
             ttlSeconds: { type: "integer", minimum: 1 },
-            syncRemote: { type: "boolean" },
-            awaitRemoteSync: { type: "boolean" },
+            syncRemote: {
+              type: "boolean",
+              description:
+                "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+            },
+            awaitRemoteSync: {
+              type: "boolean",
+              description:
+                "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+            },
           },
         },
         transport: {
@@ -833,7 +842,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "session_unlock",
         title: "Unlock Senti Files",
         description:
-          "Release session-scoped file locks held by an agent.",
+          "Release authoritative session-scoped file leases held by an agent without writing to the session transcript.",
         input_schema: {
           type: "object",
           additionalProperties: false,
@@ -849,8 +858,16 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
             },
             reason: { type: "string" },
             force: { type: "boolean" },
-            syncRemote: { type: "boolean" },
-            awaitRemoteSync: { type: "boolean" },
+            syncRemote: {
+              type: "boolean",
+              description:
+                "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+            },
+            awaitRemoteSync: {
+              type: "boolean",
+              description:
+                "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+            },
           },
         },
         transport: {
@@ -879,7 +896,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "session_locks",
         title: "List Senti File Locks",
         description:
-          "List active file locks for a session.",
+          "List active authoritative file leases for a session.",
         input_schema: {
           type: "object",
           additionalProperties: false,

package/src/mcp/session-stdio-server.js

@@ -7,16 +7,19 @@ import {
   buildCliCommandMcpTools,
   createCliCommandMcpToolHandlers,
 } from "./cli-command-tools.js";
-import { appendToStream } from "../session/stream.js";
+import { appendToStream, readStream } from "../session/stream.js";
 import { listFileLocks, lockFile, unlockFile } from "../session/file-locks.js";
 import { eventMatchesAgent } from "../session/listener.js";
 import { isSessionControlEvent } from "../session/control-events.js";
+import { buildObservations } from "../session/recall/observations.js";
+import { createMemoryService } from "../engram/index.js";
 import {
   createSessionMessageAction,
   listSessionMessageActions,
   pollSessionEvents,
   pollSessionEventsBefore,
   syncSessionEventToApi,
+  updateSessionReadCursor,
 } from "../session/sync.js";
 
 export const SESSION_MCP_SERVER_NAME = "sentinelayer-session-mcp";
@@ -185,6 +188,27 @@ function summarizeSessionEvent(event = {}) {
   });
 }
 
+function latestReadCursorTarget(events = [], fallbackCursor = "") {
+  let targetSequenceId = null;
+  let targetCursor = normalizeString(fallbackCursor);
+  for (const event of Array.isArray(events) ? events : []) {
+    const sequenceId = normalizePositiveInteger(
+      event?.sequenceId ?? event?.sequence_id,
+      null,
+    );
+    if (
+      sequenceId &&
+      (targetSequenceId === null || sequenceId >= targetSequenceId)
+    ) {
+      targetSequenceId = sequenceId;
+      targetCursor = normalizeString(event?.cursor) || targetCursor;
+    }
+  }
+  return targetSequenceId || targetCursor
+    ? { targetSequenceId, targetCursor }
+    : null;
+}
+
 function sessionEventMatchesClientMessageId(event, clientMessageId) {
   const normalizedClientMessageId = normalizeString(clientMessageId);
   if (!normalizedClientMessageId || !isPlainObject(event)) {
@@ -368,7 +392,9 @@ async function confirmSessionEventVisible(
       }
       lastReason = "not_visible";
       const nextCursor = normalizeString(result.cursor);
-      if (!events.length || !nextCursor || nextCursor === pageCursor) {
+      const scanExhausted = result.scanExhausted ?? result.scan_exhausted;
+      const emptyScanCanContinue = !events.length && scanExhausted === false;
+      if (!nextCursor || nextCursor === pageCursor || (!events.length && !emptyScanCanContinue)) {
         break;
       }
       pageCursor = nextCursor;
@@ -514,7 +540,9 @@ async function readSessionHistoryWindow({
       events.push(...materialEvents);
       const nextCursor = normalizeString(result.cursor) || pageCursor;
       responseCursor = nextCursor || responseCursor;
-      if (!rawEvents.length || !nextCursor || nextCursor === pageCursor) break;
+      const scanExhausted = result.scanExhausted ?? result.scan_exhausted;
+      const emptyScanCanContinue = !rawEvents.length && scanExhausted === false;
+      if (!nextCursor || nextCursor === pageCursor || (!rawEvents.length && !emptyScanCanContinue)) break;
       pageCursor = nextCursor;
       continue;
     }
@@ -836,6 +864,7 @@ export function createSessionMcpToolHandlers({
   pollSessionEventsBeforeFn = pollSessionEventsBefore,
   listSessionMessageActionsFn = listSessionMessageActions,
   createSessionMessageActionFn = createSessionMessageAction,
+  updateSessionReadCursorFn = updateSessionReadCursor,
   lockFileFn = lockFile,
   unlockFileFn = unlockFile,
   listFileLocksFn = listFileLocks,
@@ -845,6 +874,29 @@ export function createSessionMcpToolHandlers({
   uuidFn = randomUUID,
   now = () => new Date().toISOString(),
 } = {}) {
+  // ENGRAM §2 (Memory-as-a-Service): session is namespace #1. The SL-specific
+  // session adapter maps a session's events to the generic observation model,
+  // which keeps the detachable engram core (src/engram/*) free of any
+  // session-runtime import. Generic namespaces (project:/org:/ns:) prove the
+  // engine is sellable on its own.
+  const memoryService = createMemoryService({
+    storeRoot: targetPath,
+    adapters: {
+      session: async (sessionId) => {
+        const events = await readStream(sessionId, { targetPath, tail: 0 }).catch(() => []);
+        return buildObservations(events, { sessionId }).observations;
+      },
+    },
+  });
+  const memoryCaller = (input = {}) => {
+    const agentId = normalizeString(input.agentId || input.agent_id) || "cli-user";
+    return {
+      id: agentId,
+      kind: agentId.startsWith("guest") ? "guest" : "agent",
+      // AIdenID verification is external (§2.1); P0 writes are non-authoritative.
+      verified: false,
+    };
+  };
   return {
     async poll_inbox(input = {}) {
       const sessionId = requireSessionId(input);
@@ -891,6 +943,14 @@ export function createSessionMcpToolHandlers({
       const recentHumanActivity = actionResult?.ok
         ? recentHumanActivityFromActions(actionResult, { limit: actionLimit })
         : [];
+      const readTarget = latestReadCursorTarget(result.events, result.cursor);
+      const readCursor = readTarget
+        ? await updateSessionReadCursorFn(sessionId, {
+            targetPath,
+            ...readTarget,
+            agentId,
+          })
+        : null;
 
       return {
         ok: true,
@@ -902,6 +962,7 @@ export function createSessionMcpToolHandlers({
         inboxCount: events.length,
         recentHumanActivityCount: recentHumanActivity.length,
         recentHumanActivity,
+        readCursor,
         actionProjection: actionResult
           ? {
               ok: Boolean(actionResult.ok),
@@ -966,6 +1027,21 @@ export function createSessionMcpToolHandlers({
       const recentHumanActivity = actionResult?.ok
         ? recentHumanActivityFromActions(actionResult, { limit: actionLimit })
         : [];
+      const readAgentId = normalizeAgentId(
+        input.agentId ||
+        input.agent_id ||
+        input.agent ||
+        process.env.SENTINELAYER_AGENT_ID,
+        "",
+      );
+      const readTarget = latestReadCursorTarget(events, result.cursor);
+      const readCursor = readTarget
+        ? await updateSessionReadCursorFn(sessionId, {
+            targetPath,
+            ...readTarget,
+            agentId: readAgentId,
+          })
+        : null;
 
       return {
         ok: true,
@@ -979,6 +1055,7 @@ export function createSessionMcpToolHandlers({
         pageCount: normalizePositiveInteger(result.pages, 0),
         recentHumanActivityCount: recentHumanActivity.length,
         recentHumanActivity,
+        readCursor,
         actionProjection: actionResult
           ? {
               ok: Boolean(actionResult.ok),
@@ -1061,8 +1138,6 @@ export function createSessionMcpToolHandlers({
           intent,
           ttlSeconds,
           targetPath,
-          syncRemote: input.syncRemote !== false && input.sync_remote !== false,
-          awaitRemoteSync: input.awaitRemoteSync !== false && input.await_remote_sync !== false,
         });
         results.push({
           file: normalizeString(result?.file) || file,
@@ -1094,10 +1169,7 @@ export function createSessionMcpToolHandlers({
       for (const file of files) {
         const result = await unlockFileFn(sessionId, agentId, file, {
           reason,
-          force: false,
           targetPath,
-          syncRemote: input.syncRemote !== false && input.sync_remote !== false,
-          awaitRemoteSync: input.awaitRemoteSync !== false && input.await_remote_sync !== false,
         });
         results.push({
           file: normalizeString(result?.file) || file,
@@ -1170,15 +1242,113 @@ export function createSessionMcpToolHandlers({
         sleepFn,
       });
     },
+    async "memory.write"(input = {}) {
+      return memoryService.tools.write({
+        scope: input.scope,
+        items: input.items,
+        caller: memoryCaller(input),
+      });
+    },
+    async "memory.recall"(input = {}) {
+      return memoryService.tools.recall({
+        scope: input.scope,
+        query: input.query,
+        k: input.k,
+        role: input.role,
+        caller: memoryCaller(input),
+      });
+    },
+    async "memory.summarize"(input = {}) {
+      return memoryService.tools.summarize({
+        scope: input.scope,
+        focus: input.focus,
+        k: input.k,
+        caller: memoryCaller(input),
+      });
+    },
   };
 }
 
 export const SESSION_MCP_TOOLS = Object.freeze([
+  {
+    name: "memory.write",
+    title: "ENGRAM memory.write",
+    description:
+      "Remember facts/decisions/docs/snippets into a scoped namespace. Idempotent (content-hash dedup); every write is trust-sealed (verified -> authoritative; unverified/guest -> retrievable-but-marked, never authoritative).",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["scope", "items"],
+      properties: {
+        scope: {
+          type: "string",
+          minLength: 1,
+          description: "Namespace scope: session:<id> | project:<name> | org:<name> | agent:<id> | ns:<name>.",
+        },
+        items: {
+          type: "array",
+          minItems: 1,
+          maxItems: MAX_TOOL_LIMIT,
+          items: {
+            type: "object",
+            required: ["text"],
+            properties: {
+              text: { type: "string", minLength: 1, maxLength: MAX_MESSAGE_CHARS },
+              kind: { type: "string" },
+              topics: { type: "array", items: { type: "string" } },
+              files: { type: "array", items: { type: "string" } },
+              mentions: { type: "array", items: { type: "string" } },
+              sealed: { type: "boolean" },
+            },
+          },
+        },
+        agentId: { type: "string" },
+      },
+    },
+    security: { scopes: ["memory:write"], requires_human_approval: false, kill_switch: "enabled" },
+  },
+  {
+    name: "memory.recall",
+    title: "ENGRAM memory.recall",
+    description:
+      "Recall the top-K relevant memories from a scoped namespace (dense int8 exact-scan + BM25 + RRF + bounded graph diffusion + ACT-R), each with a one-line provenance path. Deterministic + auditable.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["scope", "query"],
+      properties: {
+        scope: { type: "string", minLength: 1 },
+        query: { type: "string", minLength: 2 },
+        k: { type: "integer", minimum: 1, maximum: 50, default: 12 },
+        role: { type: "string" },
+        agentId: { type: "string" },
+      },
+    },
+    security: { scopes: ["memory:read"], durable_receipt_required: true, requires_human_approval: false, kill_switch: "enabled" },
+  },
+  {
+    name: "memory.summarize",
+    title: "ENGRAM memory.summarize",
+    description:
+      "Summarize a namespace focused on a topic: recall DETERMINISTICALLY selects the relevant subset, then a renderer GENERATES prose over ONLY that subset (never a model in selection).",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["scope", "focus"],
+      properties: {
+        scope: { type: "string", minLength: 1 },
+        focus: { type: "string", minLength: 2 },
+        k: { type: "integer", minimum: 1, maximum: 50, default: 12 },
+        agentId: { type: "string" },
+      },
+    },
+    security: { scopes: ["memory:read"], durable_receipt_required: true, requires_human_approval: false, kill_switch: "enabled" },
+  },
   {
     name: "poll_inbox",
     title: "Poll Senti Inbox",
     description:
-      "Poll durable SentinelLayer session events after an optional cursor and return only events addressed or visible to the agent.",
+      "Poll durable SentinelLayer session events after an optional cursor, return only events addressed or visible to the agent, and advance one monotonic read cursor.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1200,13 +1370,14 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "read_history",
     title: "Read Senti History",
     description:
-      "Hydrate a bounded recent, older, or after-cursor session transcript window without recipient filtering.",
+      "Hydrate a bounded recent, older, or after-cursor session transcript window and advance one monotonic read cursor without appending view events.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
       required: ["sessionId"],
       properties: {
         sessionId: { type: "string", minLength: 1 },
+        agentId: { type: "string", minLength: 1 },
         cursor: { type: "string" },
         beforeSequence: { type: "integer", minimum: 1 },
         limit: { type: "integer", minimum: 1, maximum: MAX_TOOL_LIMIT, default: DEFAULT_TOOL_LIMIT },
@@ -1248,7 +1419,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_action",
     title: "Record Senti Session Action",
     description:
-      "Record a low-noise message action such as ack, working_on, disregard, view, like, dislike, or reply against a target session event.",
+      "Record a low-noise message action such as ack, working_on, disregard, like, dislike, or reply; view advances the monotonic read cursor instead of appending an action.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1315,7 +1486,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_lock",
     title: "Lock Senti Files",
     description:
-      "Claim session-scoped file locks before editing files, using the same fail-closed lock registry as the CLI.",
+      "Claim session-scoped file leases through the authoritative SentinelLayer API before editing. Lease lifecycle operations never create session events.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1331,8 +1502,18 @@ export const SESSION_MCP_TOOLS = Object.freeze([
         },
         intent: { type: "string" },
         ttlSeconds: { type: "integer", minimum: 1, default: 300 },
-        syncRemote: { type: "boolean", default: true },
-        awaitRemoteSync: { type: "boolean", default: true },
+        syncRemote: {
+          type: "boolean",
+          default: true,
+          description:
+            "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+        },
+        awaitRemoteSync: {
+          type: "boolean",
+          default: true,
+          description:
+            "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+        },
       },
     },
   },
@@ -1340,7 +1521,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_unlock",
     title: "Unlock Senti Files",
     description:
-      "Release session-scoped file locks held by an agent.",
+      "Release authoritative session-scoped file leases held by an agent without writing to the session transcript.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1355,8 +1536,18 @@ export const SESSION_MCP_TOOLS = Object.freeze([
           ],
         },
         reason: { type: "string" },
-        syncRemote: { type: "boolean", default: true },
-        awaitRemoteSync: { type: "boolean", default: true },
+        syncRemote: {
+          type: "boolean",
+          default: true,
+          description:
+            "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+        },
+        awaitRemoteSync: {
+          type: "boolean",
+          default: true,
+          description:
+            "Deprecated compatibility input; ignored because the authenticated API is always authoritative.",
+        },
       },
     },
   },
@@ -1364,7 +1555,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_locks",
     title: "List Senti File Locks",
     description:
-      "List active file locks for a session.",
+      "List active authoritative file leases for a session.",
     inputSchema: {
       type: "object",
       additionalProperties: false,