sentinelayer-cli 0.43.0 → 0.44.0

package/README.md

@@ -164,11 +164,13 @@ sl session action <session-id> working_on --target-sequence <n>
 ```
 
 For a room that requires agent admission, the agent declares its goal, requested
-actions, and TTL. The CLI creates an agent-held Ed25519 identity, waits for a
-human decision, then waits for the minted AIdenID email and verified signed
-purpose receipt. Only after that evidence is ready does it claim the approved
-grant with proof of possession and join. The private key and scoped credential
-are stored locally and are never printed:
+actions, and TTL. The CLI creates an agent-held Ed25519 identity and waits for a
+human decision. When the API reports identity readiness on the approved
+admission, the CLI also waits for the minted AIdenID email and verified signed
+purpose receipt before it claims; when the API does not report it, the approved
+grant is claimed directly. The claim uses proof of possession, then the agent
+joins. The private key and scoped credential are stored locally and are never
+printed:
 
 ```bash
 # Agent: request and wait for the owner's decision (maximum grant TTL is 24h).
@@ -190,20 +192,27 @@ sl session access approve <session-id> <admission-id> \
 # sl session access revoke <session-id> <admission-id> --reason "work complete"
 ```
 
-Approval queues the AIdenID email and purpose-receipt work. `session access
-list --json` reports the real `email`, `purpose`, and Jev status; it does not
-invent successful issuance while those jobs are pending or unavailable, and
-the API withholds the claim challenge until both identity artifacts are ready.
+`session access list --json` reports the `email`, `purpose`, and Jev status the
+API returns; the CLI does not invent successful issuance. On an API that gates
+the claim on identity evidence, approval queues the AIdenID email and
+purpose-receipt work and the claim challenge is withheld until both are ready.
+On an API that does not, approval issues the claim challenge directly.
 The agent must re-run `session join` with the same goal, scope, and TTL after an
 asynchronous request so it can claim and verify its live session-bound receipt.
-New rooms default to fail-closed `required` mode. Existing rooms retain their
-stored `legacy` mode until an owner explicitly sets `required`; the mode command
-is the activation step for those pre-existing rooms.
+A room's admission mode is whatever the API stored for it; `session access list`
+shows it, and an owner changes it with `session access mode <session-id>
+required` (or `legacy`).
+
+The owner actions (`approve`, `deny`, `revoke`, `mode`) run on the owner's own
+session. They are unavailable in an agent context, meaning `SENTINELAYER_AGENT_ID`
+is set or agent admission credentials are stored on the machine; owners use the
+web dashboard from such machines. `session access` commands are not exposed
+through the MCP CLI bridge.
 
 Sentinelayer includes a deterministic session coordination surface for multi-agent coding loops:
 
 - session event stream and replay (`start`, `join`, `say`, `read`, `status`, `leave`, `list`, `kill`)
-- low-noise message actions (`react ack|like|dislike`, `action working_on|disregard`, `reply`/`comment`, `actions`) plus one monotonic per-agent read cursor (`view`)
+- low-noise message actions (`react ack|like|dislike|unlike|undislike`, `action working_on|disregard`, `reply`/`comment`, `actions`) plus one monotonic per-agent read cursor (`view`)
 - agent lifecycle controls (join/ephemeral TTL presence/leave/kill); listener liveness never enters the durable transcript
 - recap and context briefing for late-joining agents
 - analytics + lineage artifacts at session closeout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -111,6 +111,11 @@ import {
   currentAdmittedAgent,
   withAgentAdmission,
 } from "../session/admission-auth.js";
+import {
+  SESSION_REACTION_TYPES,
+  isSessionReactionType,
+  submitSessionReaction,
+} from "../session/reactions.js";
 import {
   claimTicket,
   listTickets,
@@ -564,10 +569,16 @@ const SESSION_MESSAGE_ACTION_TYPES = new Set([
   "reply",
   "like",
   "dislike",
+  "unlike",
+  "undislike",
   "disregard",
   "view",
 ]);
 
+// like/dislike/unlike/undislike all go through src/session/reactions.js, the path the
+// local MCP server shares; `ack` keeps the plain message-action path.
+const SESSION_REACT_COMMAND_TYPES = Object.freeze(["ack", ...SESSION_REACTION_TYPES]);
+
 const SESSION_MESSAGE_ACTION_ALIASES = new Map([
   ["comment", "reply"],
 ]);
@@ -599,6 +610,16 @@ const SESSION_MESSAGE_ACTION_DESCRIPTIONS = Object.freeze([
     command: "sl session react <id> dislike --target-sequence <n>",
     description: "Negative lightweight feedback. Use --target-action-id <uuid> to react to a threaded reply.",
   },
+  {
+    type: "unlike",
+    command: "sl session react <id> unlike --target-sequence <n>",
+    description: "Retract your own active like. Refused when you have none; needs a server with reaction undo.",
+  },
+  {
+    type: "undislike",
+    command: "sl session react <id> undislike --target-sequence <n>",
+    description: "Retract your own active dislike. Refused when you have none; needs a server with reaction undo.",
+  },
   {
     type: "disregard",
     command: "sl session action <id> disregard --target-sequence <n>",
@@ -630,7 +651,7 @@ function shortSha256(value) {
 
 function actionEventType(actionType) {
   if (actionType === "reply") return "session_reply";
-  if (actionType === "like" || actionType === "dislike") return "session_reaction";
+  if (isSessionReactionType(actionType)) return "session_reaction";
   return "session_action";
 }
 
@@ -686,6 +707,7 @@ function buildSessionActionEvent(sessionId, action = {}) {
       }),
     );
   const actorId = actionActorId(action);
+  const collapsedIntoActionId = normalizeString(action.collapsedIntoActionId ?? action.collapsed_into_action_id);
   const event = createAgentEvent({
     event: actionEventType(actionType),
     agent: {
@@ -710,6 +732,8 @@ function buildSessionActionEvent(sessionId, action = {}) {
       metadata: action.metadata && typeof action.metadata === "object" ? action.metadata : undefined,
       message: actionDisplayMessage(action),
       source: "session_action",
+      // A retained no-op reaction key (sentinelayer-api#914): evidence, not a reaction.
+      ...(collapsedIntoActionId ? { collapsedIntoActionId } : {}),
     },
   });
   event.eventId = `session-action-${id}`;
@@ -4282,6 +4306,21 @@ export function registerSessionCommand(program) {
       );
     }
     const agentId = identity.agentId;
+    if (isSessionReactionType(normalizedActionType)) {
+      return runReactionCommand({
+        sessionId: normalizedSessionId,
+        reaction: normalizedActionType,
+        agentId,
+        targetPath,
+        targetSequenceId,
+        targetCursor,
+        targetActionId,
+        note,
+        options,
+        command,
+        commandName,
+      });
+    }
     const idempotencyKey =
       normalizeString(options.idempotencyKey) ||
       defaultActionIdempotencyKey({
@@ -4364,6 +4403,89 @@ export function registerSessionCommand(program) {
     return payload;
   }
 
+  // like/dislike/unlike/undislike: the shared reaction path (src/session/reactions.js)
+  // decides admission, the operation key and the outcome; this only mirrors and prints.
+  // `--idempotency-key` is a RETRY of the intent that minted that key.
+  async function runReactionCommand({
+    sessionId,
+    reaction,
+    agentId,
+    targetPath,
+    targetSequenceId,
+    targetCursor,
+    targetActionId,
+    note,
+    options,
+    command,
+    commandName,
+  }) {
+    const outcome = await submitSessionReaction({
+      surface: "cli",
+      sessionId,
+      agentId,
+      reaction,
+      targetSequenceId,
+      targetCursor,
+      targetActionId,
+      note,
+      idempotencyKey: options.idempotencyKey,
+      targetPath,
+    });
+    let event = null;
+    let localAppend = { appended: false, reason: "not_recorded" };
+    if (outcome.action) {
+      const appended = await appendActionEventIfMissing(
+        sessionId,
+        buildSessionActionEvent(sessionId, outcome.action),
+        { targetPath },
+      );
+      event = appended.event;
+      localAppend = { appended: Boolean(appended.appended), reason: appended.reason || "" };
+    }
+    let evidenceEvent = null;
+    if (outcome.collapsedActionId && outcome.action) {
+      // Mirror the server's retained no-op row: this request's key, collapsed into
+      // the active reaction it repeated.
+      const appended = await appendActionEventIfMissing(
+        sessionId,
+        buildSessionActionEvent(sessionId, {
+          id: outcome.collapsedActionId,
+          actionType: reaction,
+          targetSequenceId: outcome.action.targetSequenceId,
+          targetCursor: outcome.action.targetCursor,
+          targetActionId: outcome.action.targetActionId,
+          actorKind: outcome.action.actorKind,
+          actorId: outcome.action.actorId,
+          actorRole: outcome.action.actorRole,
+          idempotencyKey: outcome.operationKey,
+          collapsedIntoActionId: outcome.action.id,
+        }),
+        { targetPath },
+      );
+      evidenceEvent = appended.event;
+    }
+    const payload = {
+      command: commandName,
+      targetPath,
+      ...outcome,
+      event,
+      evidenceEvent,
+      localAppend,
+    };
+    if (!outcome.ok) process.exitCode = 1;
+    if (shouldEmitJson(options, command)) {
+      console.log(JSON.stringify(payload, null, 2));
+      return payload;
+    }
+    if (!outcome.ok) {
+      console.error(pc.yellow(outcome.message));
+      return payload;
+    }
+    if (event) console.log(formatEventLine(event));
+    if (outcome.outcome !== "applied" || !event) console.log(pc.gray(outcome.message));
+    return payload;
+  }
+
   session
     .command("actions")
     .description("List supported low-noise message actions with examples")
@@ -4390,7 +4512,7 @@ export function registerSessionCommand(program) {
   session
     .command("action <sessionId> <actionType>")
     .description(
-      "Create a message action for a target session event (ack, working_on, reply/comment, like, dislike, disregard, view)",
+      "Create a message action for a target session event (ack, working_on, reply/comment, like, dislike, unlike, undislike, disregard, view)",
     )
     .option("--target-sequence <n>", "Target event sequence id")
     .option("--target-cursor <cursor>", "Target event cursor")
@@ -4406,18 +4528,23 @@ export function registerSessionCommand(program) {
 
   session
     .command("react <sessionId> <reaction>")
-    .description("React to or acknowledge a target session event with ack, like, or dislike")
+    .description(
+      "React to or acknowledge a target session event with ack, like, or dislike; retract your own like/dislike with unlike/undislike",
+    )
     .option("--target-sequence <n>", "Target event sequence id")
     .option("--target-cursor <cursor>", "Target event cursor")
     .option("--target-action-id <uuid>", "Target a threaded reply/action by action UUID")
     .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
-    .option("--idempotency-key <key>", "Explicit idempotency key")
+    .option(
+      "--idempotency-key <key>",
+      "Retry an earlier reaction as the SAME intent by resending its operationKey (without it, each call is a new intent)",
+    )
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, reaction, options, command) => {
       const normalizedReaction = normalizeSessionMessageActionType(reaction);
-      if (!["ack", "like", "dislike"].includes(normalizedReaction)) {
-        throw new Error("reaction must be one of: ack, like, dislike.");
+      if (!SESSION_REACT_COMMAND_TYPES.includes(normalizedReaction)) {
+        throw new Error(`reaction must be one of: ${SESSION_REACT_COMMAND_TYPES.join(", ")}.`);
       }
       await runMessageActionCommand({
         sessionId,

package/src/mcp/cli-command-tools.js

@@ -64,6 +64,9 @@ const SENSITIVE_COMMAND_PREFIXES = [
   "ai.identity.target.",
   "ai.identity.site.",
   "ai.identity.legal-hold.",
+  // Room access administration (request/list/status/approve/deny/revoke/mode) belongs to
+  // the room owner's own session; operators use the direct CLI or the web dashboard.
+  "session.access.",
 ];
 const REDACTION_MARKER = "[REDACTED]";
 

package/src/mcp/registry.js

@@ -655,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, like, dislike, or reply; view advances the monotonic read cursor instead of appending an action.",
+          "Record a low-noise message action such as ack, working_on, disregard, like, dislike, unlike, undislike, or reply; view advances the monotonic read cursor instead of appending an action.",
         input_schema: {
           type: "object",
           additionalProperties: false,
@@ -665,7 +665,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
             agentId: { type: "string" },
             actionType: {
               type: "string",
-              enum: ["ack", "working_on", "reply", "like", "dislike", "disregard", "view"],
+              enum: ["ack", "working_on", "reply", "like", "dislike", "unlike", "undislike", "disregard", "view"],
             },
             targetSequenceId: { type: "integer", minimum: 1 },
             targetCursor: { type: "string" },
@@ -702,7 +702,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
         name: "session_react",
         title: "React To Senti Message",
         description:
-          "Acknowledge or react to a target session event with ack, like, or dislike.",
+          "Acknowledge or react to a target session event with ack, like, or dislike, or retract your own like/dislike with unlike/undislike. Reactions report an outcome and an operation key; resend that key as idempotencyKey only to retry the same intent.",
         input_schema: {
           type: "object",
           additionalProperties: false,
@@ -710,7 +710,7 @@ export function buildSentinelayerSessionRegistryTemplate({ generatedAt = new Dat
           properties: {
             sessionId: { type: "string" },
             agentId: { type: "string" },
-            reaction: { type: "string", enum: ["ack", "like", "dislike"] },
+            reaction: { type: "string", enum: ["ack", "like", "dislike", "unlike", "undislike"] },
             targetSequenceId: { type: "integer", minimum: 1 },
             targetCursor: { type: "string" },
             targetActionId: { type: "string" },

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

@@ -13,6 +13,12 @@ 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 { assertCanonicalAgentId, canonicalAgentId, withAgentAdmission } from "../session/admission-auth.js";
+import {
+  SESSION_REACTION_TYPES,
+  isSessionReactionType,
+  submitSessionReaction,
+} from "../session/reactions.js";
 import {
   createSessionMessageAction,
   listSessionMessageActions,
@@ -44,9 +50,12 @@ const SESSION_MESSAGE_ACTION_TYPES = new Set([
   "reply",
   "like",
   "dislike",
+  "unlike",
+  "undislike",
   "disregard",
   "view",
 ]);
+const SESSION_REACT_TYPES = Object.freeze(["ack", ...SESSION_REACTION_TYPES]);
 const SESSION_MESSAGE_ACTION_ALIASES = new Map([["comment", "reply"]]);
 
 function normalizeString(value) {
@@ -701,6 +710,25 @@ async function runSessionAction({
   const normalizedActionType = normalizeSessionMessageActionType(actionType || input.actionType || input.action_type);
   const target = requireSessionActionTarget(input);
   const normalizedNote = truncateText(note || input.note || input.message || input.text || "").text;
+  if (isSessionReactionType(normalizedActionType)) {
+    // The same path as the native CLI: canonical fail-closed admission, a fresh
+    // operation key per new intent (an explicit idempotencyKey is a retry), and a
+    // truthful outcome. The raw agent id is passed so a non-canonical spelling is
+    // refused rather than silently aliased.
+    return submitSessionReaction({
+      surface: "mcp",
+      sessionId,
+      agentId: normalizeString(input.agentId || input.agent_id || input.agent),
+      reaction: normalizedActionType,
+      ...target,
+      note: normalizedNote,
+      idempotencyKey: normalizeString(input.idempotencyKey || input.idempotency_key),
+      targetPath,
+      timeoutMs: normalizePositiveInteger(input.timeoutMs || input.timeout_ms, 15_000),
+      dryRun: Boolean(input.dryRun || input.dry_run),
+      createSessionMessageActionFn,
+    });
+  }
   const idempotencyKey =
     normalizeString(input.idempotencyKey || input.idempotency_key) ||
     defaultActionIdempotencyKey({
@@ -858,6 +886,47 @@ async function persistSessionEvent({
   };
 }
 
+// Local MCP tools that act AS an agent: post, raise attention, react, reply, act on a
+// message, lease files, or advance that agent's read cursor. Each runs inside the
+// agent's admission scope, the same canonical path native `sl session` actor commands
+// use. A live stored admission is the only credential its requests carry; an expired,
+// malformed or mis-bound one is refused before any request; a credential the API
+// refuses (401/403) is final. With no stored admission a tool behaves as before.
+export const SESSION_MCP_ACTOR_TOOLS = Object.freeze([
+  "poll_inbox",
+  "read_history",
+  "send_message",
+  "attention_request",
+  "session_action",
+  "session_react",
+  "session_reply",
+  "session_lock",
+  "session_unlock",
+]);
+
+function actorAgentId(toolName, input = {}) {
+  const raw =
+    normalizeString(input.agentId || input.agent_id || input.agent) ||
+    (toolName === "read_history" ? normalizeString(process.env.SENTINELAYER_AGENT_ID) : "");
+  if (!raw) return "";
+  // One canonical identity for authorisation and execution (see admission-auth.js).
+  assertCanonicalAgentId(raw, "agentId");
+  return canonicalAgentId(raw);
+}
+
+function routeActorToolsThroughAdmission(handlers) {
+  for (const name of SESSION_MCP_ACTOR_TOOLS) {
+    const run = handlers[name];
+    handlers[name] = async (input = {}) => {
+      const agentId = actorAgentId(name, input);
+      // No agent named: the tool's own validation reports it (read_history reads as the user).
+      if (!agentId) return run(input);
+      return withAgentAdmission(requireSessionId(input), agentId, () => run(input));
+    };
+  }
+  return handlers;
+}
+
 export function createSessionMcpToolHandlers({
   targetPath = process.cwd(),
   pollSessionEventsFn = pollSessionEvents,
@@ -897,7 +966,7 @@ export function createSessionMcpToolHandlers({
       verified: false,
     };
   };
-  return {
+  const handlers = {
     async poll_inbox(input = {}) {
       const sessionId = requireSessionId(input);
       const agentId = requireAgentId(input);
@@ -1105,8 +1174,8 @@ export function createSessionMcpToolHandlers({
 
     async session_react(input = {}) {
       const reaction = normalizeSessionMessageActionType(input.reaction || input.actionType || input.action_type);
-      if (!["ack", "like", "dislike"].includes(reaction)) {
-        throw new Error("reaction must be one of: ack, like, dislike.");
+      if (!SESSION_REACT_TYPES.includes(reaction)) {
+        throw new Error(`reaction must be one of: ${SESSION_REACT_TYPES.join(", ")}.`);
       }
       return runSessionAction({
         input,
@@ -1267,6 +1336,7 @@ export function createSessionMcpToolHandlers({
       });
     },
   };
+  return routeActorToolsThroughAdmission(handlers);
 }
 
 export const SESSION_MCP_TOOLS = Object.freeze([
@@ -1419,7 +1489,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, like, dislike, or reply; view advances the monotonic read cursor instead of appending an action.",
+      "Record a low-noise message action such as ack, working_on, disregard, like, dislike, unlike, undislike, or reply; view advances the monotonic read cursor instead of appending an action.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1442,7 +1512,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_react",
     title: "React To Senti Message",
     description:
-      "Acknowledge or react to a target session event with ack, like, or dislike.",
+      "Acknowledge or react to a target session event with ack, like, or dislike, or retract your own like/dislike with unlike/undislike. Reactions report an outcome and an operation key; resend that key as idempotencyKey only to retry the same intent.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1450,7 +1520,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
       properties: {
         sessionId: { type: "string", minLength: 1 },
         agentId: { type: "string", minLength: 1 },
-        reaction: { type: "string", enum: ["ack", "like", "dislike"] },
+        reaction: { type: "string", enum: [...SESSION_REACT_TYPES] },
         targetSequenceId: { type: "integer", minimum: 1 },
         targetCursor: { type: "string" },
         targetActionId: { type: "string" },

package/src/session/admission-access.js

@@ -10,12 +10,37 @@ import process from "node:process";
 
 import { requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
+import { hasStoredAdmissionCredentials } from "./admission.js";
+import { currentAdmittedAgent } from "./admission-auth.js";
 import {
   SESSION_MUTATION_ORIGIN,
   createSessionMutationHeaders,
   createSessionMutationIdempotencyKey,
 } from "./invitations.js";
 
+/**
+ * Approve, deny, revoke and mode changes are the room owner's decisions, made with the
+ * owner's own session. They are unavailable while this process is an agent context:
+ * SENTINELAYER_AGENT_ID is set, an agent admission scope is in force, or this machine
+ * stores agent admission credentials. Checked before any credential lookup or request.
+ */
+export async function assertOwnerAccessContext({ env = process.env, homeDir } = {}) {
+  let why = "";
+  if (normalizeString(env.SENTINELAYER_AGENT_ID)) {
+    why = "SENTINELAYER_AGENT_ID is set";
+  } else if (currentAdmittedAgent()) {
+    why = "an agent admission is in use";
+  } else if (await hasStoredAdmissionCredentials({ homeDir })) {
+    why = "agent admission credentials are stored on this machine";
+  }
+  if (why) {
+    throw new Error(
+      `Access approve, deny, revoke and mode are owner actions and are unavailable in an agent context (${why}). ` +
+        `Use the room's web dashboard, or run the command from an environment without agent credentials.`,
+    );
+  }
+}
+
 export const ADMISSION_STATUSES = Object.freeze([
   "pending",
   "approved",
@@ -171,6 +196,7 @@ export async function decideSessionAdmission(
   if (ttlSeconds !== undefined) body.ttlSeconds = ttlSeconds;
   const normalizedNote = normalizeString(note);
   if (normalizedNote) body.note = normalizedNote;
+  await assertOwnerAccessContext();
   return mutateAdmission(
     sid,
     `/${encodeURIComponent(aid)}/decision`,
@@ -202,6 +228,7 @@ export async function revokeSessionAdmission(
   const sid = required(sessionId, "session id");
   const aid = required(admissionId, "admission id");
   const normalizedReason = normalizeString(reason);
+  await assertOwnerAccessContext();
   return mutateAdmission(
     sid,
     `/${encodeURIComponent(aid)}/revoke`,
@@ -234,6 +261,7 @@ export async function setSessionAdmissionMode(
   if (!["legacy", "required"].includes(normalizedMode)) {
     throw new Error("mode must be legacy or required.");
   }
+  await assertOwnerAccessContext();
   const key = boundedIdempotencyKey(idempotencyKey, "session.admission_mode");
   const auth = await authContext(targetPath, resolveAuthSession);
   const result = await requestMutation(

package/src/session/admission.js

@@ -63,7 +63,8 @@ const ROUTE = {
   claim: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/claim",
   cancel: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/cancel",
 };
-const TERMINAL = new Set(["denied", "cancelled", "expired", "revoked"]);
+// Final admission statuses: polling stops, nothing is claimed, local request state is cleared.
+const TERMINAL = new Set(["denied", "cancelled", "expired", "revoked", "stopped"]);
 const TTL_MIN_SECONDS = 300;
 const TTL_MAX_SECONDS = 86_400;
 
@@ -242,6 +243,34 @@ export function admissionCredentialPath(sessionId, agentId, { homeDir } = {}) {
   );
 }
 
+/**
+ * Whether this machine stores ANY agent admission credential (usable or not, any
+ * session): `<home>/.sentinelayer/agents/<agent>/admissions/<session>.json`. Agent keys
+ * alone do not count. An unreadable directory counts as present, never as absence.
+ */
+export async function hasStoredAdmissionCredentials({ homeDir } = {}) {
+  const agentsDir = path.join(sentinelayerHome(homeDir), "agents");
+  let agents;
+  try {
+    agents = await fsp.readdir(agentsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return false;
+    return true;
+  }
+  for (const agent of agents) {
+    if (!agent.isDirectory()) continue;
+    let files;
+    try {
+      files = await fsp.readdir(path.join(agentsDir, agent.name, "admissions"));
+    } catch (error) {
+      if (error && error.code === "ENOENT") continue;
+      return true;
+    }
+    if (files.some((name) => name.endsWith(".json"))) return true;
+  }
+  return false;
+}
+
 /**
  * What this machine holds for (session, agent):
  *   { state: "none" }                        -- never admitted here: the legacy path applies
@@ -471,18 +500,24 @@ export async function runAdmissionJoin(
       headers: { Authorization: `Bearer ${auth.token}` },
     });
     state.status = polled.status;
-    const claimReady =
-      polled.status === "approved" &&
-      polled.identityReady === true &&
-      polled?.claim?.domain === CLAIM_DOMAIN &&
-      polled?.claim?.preimage;
-    if (polled.status === "approved" && polled.identityReady === true && !claimReady) {
-      throw new Error("Identity-ready admission did not include a valid claim challenge.");
-    }
-    if (polled.status === "approved" && polled.identityReady !== true && polled?.claim) {
-      throw new Error("Admission exposed a claim challenge before AIdenID identity evidence was ready.");
+    // Identity readiness is a server capability: a server that gates the claim on
+    // AIdenID identity evidence reports `identityReady` (true or false) on every
+    // approved poll. A server that does not report it issues the claim challenge on
+    // approval, so the claim proceeds as soon as the admission is approved.
+    const reportsIdentityReadiness =
+      polled.status === "approved" && Object.prototype.hasOwnProperty.call(polled, "identityReady");
+    const claimable =
+      polled.status === "approved" && (!reportsIdentityReadiness || polled.identityReady === true);
+    if (reportsIdentityReadiness) {
+      const claimReady = claimable && polled?.claim?.domain === CLAIM_DOMAIN && polled?.claim?.preimage;
+      if (polled.identityReady === true && !claimReady) {
+        throw new Error("Identity-ready admission did not include a valid claim challenge.");
+      }
+      if (polled.identityReady !== true && polled?.claim) {
+        throw new Error("Admission exposed a claim challenge before AIdenID identity evidence was ready.");
+      }
     }
-    if (claimReady || TERMINAL.has(polled.status) || polled.status === "active") break;
+    if (claimable || TERMINAL.has(polled.status) || polled.status === "active") break;
     const phase = polled.status === "approved" ? "identity" : "approval";
     onPending({
       admissionId: state.admissionId,

package/src/session/control-events.js

@@ -14,6 +14,8 @@ const QUIET_SESSION_ACTION_TYPES = new Set([
   "dislike",
   "disregard",
   "like",
+  "undislike",
+  "unlike",
   "view",
 ]);
 

package/src/session/reactions.js

@@ -0,0 +1,258 @@
+// reactions.js -- the ONE path every like / dislike / unlike / undislike takes, from
+// the native CLI (`sl session react|action`) and the local MCP server
+// (`session_react`, `session_action`) alike.
+//
+// Three guarantees. Separate copies of this logic once broke each of them:
+//
+//   1. Authority. The write runs inside withAgentAdmission for (session, agent): an
+//      admitted agent acts on ITS admission credential, a tombstoned (expired,
+//      malformed, mis-bound) admission is refused before any request, and nothing
+//      falls back to the human's broader token or legacy agent grants.
+//   2. Intent. The API replays a reused idempotency key instead of acting on it
+//      (sentinelayer-api#914 reaction contract), so a key derived from
+//      (type, target, actor) makes like -> unlike -> like a silent no-op. Each NEW
+//      intent gets a fresh operation key. An explicit key is a retry of the intent
+//      that minted it, and is sent unchanged.
+//   3. Truth. Every result names its outcome and carries its operation key, so an
+//      ambiguous failure (the request may have landed) can be retried as the SAME
+//      intent instead of becoming a new one that could retract a newer reaction.
+
+import { randomBytes } from "node:crypto";
+import process from "node:process";
+
+import { assertCanonicalAgentId, canonicalAgentId, withAgentAdmission } from "./admission-auth.js";
+import { createSessionMessageAction } from "./sync.js";
+
+export const SESSION_REACTION_TYPES = Object.freeze(["like", "dislike", "unlike", "undislike"]);
+const REACTION_TYPES = new Set(SESSION_REACTION_TYPES);
+const UNDO_TARGETS = new Map([
+  ["unlike", "like"],
+  ["undislike", "dislike"],
+]);
+
+// createSessionMessageAction failures that happen before any request leaves this machine.
+const NOT_SENT_REASONS = new Set([
+  "invalid_input",
+  "remote_sync_disabled_env",
+  "circuit_breaker_open",
+  "no_session",
+  "not_authenticated",
+]);
+
+/**
+ * Every outcome a reaction can have. `ok` is true only for the first three.
+ *   applied     -- this request recorded a new reaction row
+ *   no_op       -- an equal reaction was already active; nothing changed. With
+ *                  `collapsedActionId` the server retained this request as evidence.
+ *   replayed    -- an explicit (retry) key had already been recorded; the server
+ *                  returned that original result and did not re-check current state
+ *   not_active  -- an undo with nothing of this actor's active to retract (409)
+ *   unsupported -- a server without reaction undo rejected the action value (422)
+ *   refused     -- any other definitive refusal; nothing was recorded
+ *   not_sent    -- the request never left this machine; nothing was recorded
+ *   unknown     -- the request may or may not have been recorded (timeout, lost
+ *                  response, 5xx): retry with the SAME operation key
+ */
+export const SESSION_REACTION_OUTCOMES = Object.freeze([
+  "applied",
+  "no_op",
+  "replayed",
+  "not_active",
+  "unsupported",
+  "refused",
+  "not_sent",
+  "unknown",
+]);
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+export function isSessionReactionType(value) {
+  return REACTION_TYPES.has(normalizeString(value).toLowerCase());
+}
+
+/** The like/dislike an undo retracts, or "" for a non-undo. */
+export function reactionUndoTarget(value) {
+  return UNDO_TARGETS.get(normalizeString(value).toLowerCase()) || "";
+}
+
+function targetKey({ targetSequenceId, targetCursor, targetActionId }) {
+  if (normalizeString(targetActionId)) return `action:${normalizeString(targetActionId)}`;
+  if (targetSequenceId) return `seq:${targetSequenceId}`;
+  return `cursor:${normalizeString(targetCursor)}`;
+}
+
+function targetLabel({ targetSequenceId, targetCursor, targetActionId }) {
+  if (normalizeString(targetActionId)) return `reply ${normalizeString(targetActionId)}`;
+  if (targetSequenceId) return `#${targetSequenceId}`;
+  return normalizeString(targetCursor) || "target";
+}
+
+/** A key for a NEW intent. Never derived from (type, target, actor) alone. */
+export function newReactionOperationKey({ surface, reaction, agentId, ...target } = {}) {
+  return `${surface}:${reaction}:${targetKey(target)}:${agentId}:${randomBytes(8).toString("hex")}`;
+}
+
+/**
+ * The exact 422 a server without reaction undo (sentinelayer-api before #914) returns
+ * for this action: FastAPI's validation envelope around the route's action-type
+ * validator, a single entry echoing the value sent. Anything looser could relabel a
+ * different validation failure as "undo unsupported", so the match is exact.
+ */
+export function isUndoUnsupportedValidationError(result = {}, actionType = "") {
+  if (result.status !== 422) return false;
+  const detail = result.error?.detail;
+  if (!Array.isArray(detail) || detail.length !== 1) return false;
+  const [entry] = detail;
+  return (
+    entry?.type === "value_error" &&
+    Array.isArray(entry.loc) &&
+    entry.loc.length === 2 &&
+    entry.loc[0] === "body" &&
+    entry.loc[1] === "actionType" &&
+    entry.msg === "Value error, unsupported message action type" &&
+    entry.input === actionType
+  );
+}
+
+function classify(reaction, result, retry) {
+  const status = Number.isInteger(result?.status) ? result.status : null;
+  if (result?.ok && result.action) {
+    if (normalizeString(result.collapsedActionId)) return "no_op";
+    if (result.duplicate) return retry ? "replayed" : "no_op";
+    return "applied";
+  }
+  if (status === null) {
+    return NOT_SENT_REASONS.has(normalizeString(result?.reason)) ? "not_sent" : "unknown";
+  }
+  if (status >= 500) return "unknown";
+  if (isUndoUnsupportedValidationError(result, reaction)) return "unsupported";
+  if (status === 409 && reactionUndoTarget(reaction) && result.error?.error?.code === "REACTION_NOT_ACTIVE") {
+    return "not_active";
+  }
+  if (status >= 400) return "refused";
+  return "unknown";
+}
+
+function describe(outcome, { reaction, agentId, target, operationKey, reason, errorCode, collapsedActionId }) {
+  const where = targetLabel(target);
+  switch (outcome) {
+    case "applied":
+      return `${agentId} ${reaction} recorded on ${where}.`;
+    case "no_op":
+      return (
+        `No change: ${agentId} already has an active ${reaction} on ${where}.` +
+        (collapsedActionId ? ` This request is retained as evidence ${collapsedActionId}.` : "")
+      );
+    case "replayed":
+      return (
+        `Replayed: operation ${operationKey} was already recorded. The server returned its ` +
+        `original result and did not re-check the current state.`
+      );
+    case "not_active":
+      return `Nothing to undo: ${agentId} has no active ${reactionUndoTarget(reaction)} on ${where}.`;
+    case "unsupported":
+      return `This server doesn't support undo yet (no '${reaction}' action). Nothing was changed.`;
+    case "refused":
+      return `The server refused this ${reaction} (${errorCode || reason}). Nothing was recorded.`;
+    case "not_sent":
+      return `Not sent (${reason}). Nothing was recorded.`;
+    default:
+      return (
+        `Outcome unknown (${reason || "no response"}): the server may have recorded this ${reaction}. ` +
+        `To retry this same intent, resend it with idempotency key ${operationKey}; ` +
+        `without that key it is a new intent.`
+      );
+  }
+}
+
+/**
+ * Submit one reaction. Throws only for invalid input or a refused admission (before
+ * any request); every server answer, network failure and timeout is an outcome.
+ */
+export async function submitSessionReaction({
+  surface,
+  sessionId,
+  agentId,
+  reaction,
+  targetSequenceId = null,
+  targetCursor = "",
+  targetActionId = "",
+  note = "",
+  idempotencyKey = "",
+  targetPath = process.cwd(),
+  timeoutMs = 15_000,
+  dryRun = false,
+  createSessionMessageActionFn = createSessionMessageAction,
+} = {}) {
+  const sid = normalizeString(sessionId);
+  const type = normalizeString(reaction).toLowerCase();
+  if (!sid) throw new Error("session id is required.");
+  if (!REACTION_TYPES.has(type)) {
+    throw new Error(`reaction must be one of: ${SESSION_REACTION_TYPES.join(", ")}.`);
+  }
+  // One canonical identity for authorisation and execution (see admission-auth.js).
+  assertCanonicalAgentId(agentId, "agentId");
+  const agent = canonicalAgentId(agentId);
+  if (!agent) throw new Error("agentId is required.");
+  const target = {
+    targetSequenceId: targetSequenceId || null,
+    targetCursor: normalizeString(targetCursor),
+    targetActionId: normalizeString(targetActionId),
+  };
+  if (!target.targetSequenceId && !target.targetCursor && !target.targetActionId) {
+    throw new Error("Provide a target sequence, cursor, or action id.");
+  }
+  const explicitKey = normalizeString(idempotencyKey);
+  const operationKey =
+    explicitKey || newReactionOperationKey({ surface, reaction: type, agentId: agent, ...target });
+  const base = {
+    sessionId: sid,
+    agentId: agent,
+    actionType: type,
+    ...target,
+    note: normalizeString(note),
+    operationKey,
+    idempotencyKey: operationKey,
+    retry: Boolean(explicitKey),
+  };
+  if (dryRun) return { ok: true, dryRun: true, outcome: "dry_run", ...base };
+
+  const result = await withAgentAdmission(sid, agent, () =>
+    createSessionMessageActionFn(sid, {
+      actionType: type,
+      targetPath,
+      ...target,
+      note: base.note,
+      metadata: { source: surface, agentId: agent },
+      idempotencyKey: operationKey,
+      timeoutMs,
+    }),
+  );
+  const outcome = classify(type, result, base.retry);
+  const collapsedActionId = normalizeString(result?.collapsedActionId) || null;
+  const status = Number.isInteger(result?.status) ? result.status : null;
+  const reason = normalizeString(result?.reason);
+  const errorCode = normalizeString(result?.error?.error?.code) || null;
+  return {
+    ok: outcome === "applied" || outcome === "no_op" || outcome === "replayed",
+    outcome,
+    ...base,
+    duplicate: Boolean(result?.duplicate),
+    collapsedActionId,
+    status,
+    reason,
+    errorCode,
+    message: describe(outcome, {
+      reaction: type,
+      agentId: agent,
+      target,
+      operationKey,
+      reason,
+      errorCode,
+      collapsedActionId,
+    }),
+    action: result?.ok && result.action ? result.action : null,
+  };
+}

package/src/session/sync.js

@@ -19,6 +19,8 @@ const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
 const DEFAULT_SYNC_TIMEOUT_MS = 5_000;
 const MAX_CONSECUTIVE_FAILURES = 3;
 const CIRCUIT_RESET_MS = 60_000;
+// Message-action statuses whose body the caller needs to explain the refusal.
+const MESSAGE_ACTION_REFUSAL_STATUSES = Object.freeze([409, 422]);
 const SESSION_INGEST_LIMIT_PER_MINUTE = 500;
 const HUMAN_MESSAGE_LIMIT_PER_MINUTE = 10;
 const HUMAN_MESSAGE_MAX_LENGTH = 2_000;
@@ -374,6 +376,18 @@ function recordCircuitFailure(circuit, nowMs) {
   persistCircuitState();
 }
 
+// 401 and 403 refuse one credential (an expired, revoked or narrower agent admission, or
+// an identity the account has not granted). They say nothing about API health, so they
+// never count toward the machine-wide outbound breaker; every other failure does.
+function isCredentialRefusal(response) {
+  return Boolean(response) && (response.status === 401 || response.status === 403);
+}
+
+function recordOutboundFailure(response, nowMs) {
+  if (isCredentialRefusal(response)) return;
+  recordCircuitFailure(outboundCircuit, nowMs);
+}
+
 function recordCircuitSuccess(circuit) {
   if (!circuit) {
     return;
@@ -1033,18 +1047,23 @@ export async function syncSessionEventToApi(
     if (response && response.status === 403) {
       const body = forbiddenBody;
       if (isIdentityForgeryBody(body)) {
+        if (session.source === "session_admission") {
+          // An admitted agent acts only on its admission: account-level agent grants
+          // are neither created nor used for it.
+          return { synced: false, reason: "api_403" };
+        }
         const agentId = normalizeString(event?.agent?.id);
         if (!agentId || isReservedAgentIdForGrant(agentId)) {
           // Reserved or empty — server enforcement is intentional, no grant
           // attempt is meaningful. Treat as a normal 403 failure.
-          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          recordOutboundFailure(response, normalizedNowMs);
           return { synced: false, reason: "api_403" };
         }
         if (autoGrantAttemptedAgentIds.has(agentId)) {
           // We already tried to grant this identity in a prior event in this
           // process and either it succeeded but the server still says no, or
           // the grant failed. Either way, don't loop — surface the 403.
-          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          recordOutboundFailure(response, normalizedNowMs);
           return { synced: false, reason: "api_403" };
         }
         rememberAutoGrantAttempt(agentId);
@@ -1081,7 +1100,7 @@ export async function syncSessionEventToApi(
         // Treat 409 (already granted) as success — idempotent on the server.
         const grantIdempotent = grantStatus === 409;
         if (!grantOk && !grantIdempotent) {
-          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          recordOutboundFailure(grantResponse, normalizedNowMs);
           return {
             synced: false,
             reason: `grant_failed_${grantStatus || "no_response"}`,
@@ -1109,7 +1128,7 @@ export async function syncSessionEventToApi(
             autoGranted: true,
           };
         }
-        recordCircuitFailure(outboundCircuit, normalizedNowMs);
+        recordOutboundFailure(retryResponse, normalizedNowMs);
         return {
           synced: false,
           reason: `api_${retryResponse ? retryResponse.status : "no_response"}`,
@@ -1117,7 +1136,7 @@ export async function syncSessionEventToApi(
       }
     }
 
-    recordCircuitFailure(outboundCircuit, normalizedNowMs);
+    recordOutboundFailure(response, normalizedNowMs);
     return {
       synced: false,
       reason: `api_${response ? response.status : "no_response"}`,
@@ -1207,7 +1226,7 @@ async function syncSessionAuxPayload(
       { readSuccessBody: false },
     );
     if (!response || !response.ok) {
-      recordCircuitFailure(outboundCircuit, normalizedNowMs);
+      recordOutboundFailure(response, normalizedNowMs);
       return {
         synced: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -1843,7 +1862,7 @@ export async function renewSessionPresence(
           retryAfterMs: retryAfterMsFromResponse(response, payload, normalizedNowMs),
         };
       }
-      recordCircuitFailure(outboundCircuit, normalizedNowMs);
+      recordOutboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -1958,7 +1977,7 @@ export async function requestSessionListenerStop(
           retryAfterMs: retryAfterMsFromResponse(response, payload, normalizedNowMs),
         };
       }
-      recordCircuitFailure(outboundCircuit, normalizedNowMs);
+      recordOutboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -2083,7 +2102,7 @@ export async function updateSessionReadCursor(
           updated: false,
         };
       }
-      recordCircuitFailure(outboundCircuit, normalizedNowMs);
+      recordOutboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -2990,12 +3009,20 @@ export async function createSessionMessageAction(
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
+      { errorBodyStatuses: MESSAGE_ACTION_REFUSAL_STATUSES },
     );
     if (!response || !response.ok) {
-      recordCircuitFailure(outboundCircuit, normalizedNowMs);
+      const status = response ? response.status : null;
+      const refused = MESSAGE_ACTION_REFUSAL_STATUSES.includes(status);
+      // A refusal (409 nothing-to-undo, 422 a server that predates the action) is an
+      // answer about this request, not API health: it must not open the persisted
+      // breaker that guards every other outbound write.
+      if (!refused) recordOutboundFailure(response, normalizedNowMs);
       return {
         ok: false,
-        reason: `api_${response ? response.status : "no_response"}`,
+        reason: `api_${status ?? "no_response"}`,
+        status,
+        error: refused && payload && typeof payload === "object" ? payload : null,
         action: null,
       };
     }
@@ -3004,6 +3031,9 @@ export async function createSessionMessageAction(
       ok: Boolean(payload?.ok ?? true),
       reason: "",
       duplicate: Boolean(payload?.duplicate),
+      // A repeat reaction is a no-op whose key the server retains as a collapsed row
+      // (sentinelayer-api#914): the id of that evidence row.
+      collapsedActionId: normalizeString(payload?.collapsedActionId) || null,
       action: payload?.action && typeof payload.action === "object" ? payload.action : null,
     };
   } catch (error) {