sentinelayer-cli 0.46.3 → 0.46.5

package/src/commands/session.js

@@ -33,6 +33,7 @@ import {
   unregisterAgent,
 } from "../session/agent-registry.js";
 import { inferSessionAgentIdentity } from "../session/agent-identity.js";
+import { legacyJoinAdmissionRefusal, verifyLegacyAgentJoin } from "../session/agent-access.js";
 import { startSenti, stopSenti } from "../session/daemon.js";
 import {
   getDaemonStatus,
@@ -78,7 +79,6 @@ import {
   getListenerProcessStatus,
   LISTENER_PROCESS_SCAN_RETRY_TIMEOUT_MS,
   removeListenerPidRecord,
-  requestListenerProcessStop,
   summarizeLocalListenerProcesses,
   stopMatchingListenerProcesses,
   writeListenerPidRecord,
@@ -3438,6 +3438,7 @@ export function registerSessionCommand(program) {
     .option("--no-wait", "Request admission and return immediately with the approval URL")
     .option("--wait-seconds <n>", "How long to wait for approval before returning pending", "900")
     .option("--cancel-admission", "Cancel this workspace's pending admission request for the session")
+    .option("--recover-admission", "Recover a live admission with the retained agent key; requires the unchanged --goal/scope/ttl")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
@@ -3456,6 +3457,27 @@ export function registerSessionCommand(program) {
       // the local registration and every later implicit command name the same agent.
       if (!explicitAgent) assertCanonicalAgentId(legacyName, "--name");
       const requestedAgent = canonicalAgentId(explicitAgent || legacyName);
+      if (options.recoverAdmission && !normalizeString(options.goal)) {
+        throw new Error("--recover-admission requires --goal and the admission's unchanged scope/ttl.");
+      }
+      const rejectLegacyJoin = (verification, agentId) => {
+        process.exitCode = 4;
+        const payload = {
+          command: "session join", joined: false, sessionId: normalizedSessionId,
+          agentId, remoteAgentVerification: verification,
+        };
+        if (emitJson) console.log(JSON.stringify(payload, null, 2));
+        else {
+          const hint = verification.code.includes("UNAVAILABLE")
+            ? "Retry when the API/presence service is available; no new approval was requested."
+            : verification.code.includes("CONTRACT_MISMATCH")
+              ? "Verify the CLI/server contract; no new authorization was created."
+              : verification.code === "LEGACY_GRANT_ROLE_MISMATCH"
+                ? "Use the already-granted role, or request an explicit owner-approved change."
+                : "Request scoped admission with --goal, or have the owner explicitly authorize its legacy grant.";
+          console.log(pc.red(`Agent was not joined: ${verification.code}. ${hint}`));
+        }
+      };
       if (options.cancelAdmission) {
         const cancelled = await cancelAdmission(normalizedSessionId, {
           agentId: requestedAgent,
@@ -3474,6 +3496,13 @@ export function registerSessionCommand(program) {
         else console.log(`Admission request ${payload.admission.admissionId || ""} cancelled.`);
         return;
       }
+      if (requestedAgent && !normalizeString(options.goal)) {
+        const refusal = await legacyJoinAdmissionRefusal(normalizedSessionId, requestedAgent);
+        if (refusal) {
+          rejectLegacyJoin(refusal, requestedAgent);
+          return;
+        }
+      }
       // Membership first. Only a member may ask for an agent to be admitted, so an
       // invitation is accepted BEFORE the admission request, never after.
       let invitationAccept = null;
@@ -3492,13 +3521,14 @@ export function registerSessionCommand(program) {
             : null;
       }
       let admission = null;
+      let admissionJoinOptions = null;
       if (normalizeString(options.goal)) {
         const admissionAgent = requestedAgent;
         if (!admissionAgent) {
           throw new Error("--goal requires --agent <id>: admission is requested for one named agent.");
         }
         const waitSeconds = Number.parseInt(String(options.waitSeconds ?? "900"), 10);
-        admission = await runAdmissionJoin(normalizedSessionId, {
+        admissionJoinOptions = {
           agentId: admissionAgent,
           displayName: legacyName && explicitAgent ? legacyName : "",
           model: options.model,
@@ -3509,6 +3539,7 @@ export function registerSessionCommand(program) {
           actions: parseAdmissionScope(options.scope),
           ttlSeconds: parseAdmissionTtlSeconds(options.ttl),
           wait: options.wait !== false,
+          recoverActive: Boolean(options.recoverAdmission),
           waitTimeoutMs: (Number.isFinite(waitSeconds) && waitSeconds >= 0 ? waitSeconds : 900) * 1000,
           targetPath,
           onPending: ({ approveUrl, phase }) => {
@@ -3524,7 +3555,8 @@ export function registerSessionCommand(program) {
             else if (phase === "identity") console.log(pc.yellow(line));
             else console.log(line);
           },
-        });
+        };
+        admission = await runAdmissionJoin(normalizedSessionId, admissionJoinOptions);
         if (admission.status !== "active") {
           // Only an ACTIVE admission joins. Pending, denied, cancelled or expired never
           // registers the agent or materializes the room for it.
@@ -3551,6 +3583,34 @@ export function registerSessionCommand(program) {
         }
       }
 
+      const admittedAgentId = admission ? requestedAgent : "";
+      const acceptedOnboarding = normalizeSessionOnboarding(
+        invitationAcceptResult?.onboarding,
+        invitationAcceptResult?.claimedSeat,
+      );
+      const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
+      if (!admission && !explicitAgent && acceptedAgentId) {
+        assertCanonicalAgentId(acceptedAgentId, "the invitation's agent id");
+      }
+      const agentSeed = admission ? admittedAgentId : explicitAgent || acceptedAgentId || legacyName;
+      const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
+      if (admission && resolvedAgentId !== admittedAgentId) {
+        throw new Error(`join would register "${resolvedAgentId}", not the admitted agent "${admittedAgentId}".`);
+      }
+      const roleWasExplicit = optionWasSetByCli(command, "role");
+      const role =
+        normalizeString(roleWasExplicit ? options.role : acceptedOnboarding?.role || options.role) ||
+        "coder";
+      const model = normalizeString(options.model) || "cli";
+      const namedLegacyAgent = !admission && Boolean(agentSeed || normalizeString(process.env.SENTINELAYER_AGENT_ID));
+      if (namedLegacyAgent) {
+        const refusal = await legacyJoinAdmissionRefusal(normalizedSessionId, resolvedAgentId);
+        if (refusal) {
+          rejectLegacyJoin(refusal, resolvedAgentId);
+          return;
+        }
+      }
+
       // PR #483 contract: verify the session exists and the caller has access
       // BEFORE materializing local cache state. Without this we'd silently
       // create a phantom local NDJSON for a session that's archived or owned
@@ -3565,21 +3625,36 @@ export function registerSessionCommand(program) {
       // grant's receipt, and never with the human token. A cached "active" is not
       // reported until this succeeds (a revoked grant is not joined), and nothing
       // about the room is fetched on the human's authority.
-      const admittedAgentId = admission ? requestedAgent : "";
       let admissionReceipt = null;
       if (admission) {
-        try {
-          admissionReceipt = await withAgentAdmission(normalizedSessionId, admittedAgentId, () =>
+        const verifyAdmissionReceipt = async () => {
+          const receipt = await withAgentAdmission(normalizedSessionId, admittedAgentId, () =>
             fetchOwnAdmissionReceipt(normalizedSessionId, { targetPath }),
           );
           // The grant must be for EXACTLY the identity this join registers, byte for
           // byte: a receipt for any other spelling is a different agent's authority.
-          const receiptAgent = String(admissionReceipt?.agentId ?? "");
+          const receiptAgent = String(receipt?.agentId ?? "");
           if (receiptAgent !== admittedAgentId) {
             throw new Error(
               `the admission is for agent "${receiptAgent || "(none)"}", not "${admittedAgentId}"`,
             );
           }
+          return receipt;
+        };
+        try {
+          try {
+            admissionReceipt = await verifyAdmissionReceipt();
+          } catch (error) {
+            // One key-possession recovery for a stale bearer, never a different
+            // identity, denied scope, provider/network failure or generic 403.
+            if (options.recoverAdmission || !(error instanceof SentinelayerApiError) ||
+                ![401, 403].includes(error.status) || error.code !== "INVALID_TOKEN") throw error;
+            admission = await runAdmissionJoin(normalizedSessionId, {
+              ...admissionJoinOptions, recoverActive: true,
+            });
+            if (admission.status !== "active") throw new Error("The admission is not active; recovery did not join the agent.");
+            admissionReceipt = await verifyAdmissionReceipt();
+          }
         } catch (error) {
           process.exitCode = 4;
           const payload = {
@@ -3595,7 +3670,7 @@ export function registerSessionCommand(program) {
             },
           };
           if (emitJson) console.log(JSON.stringify(payload, null, 2));
-          else console.log(pc.red(`The API no longer accepts this agent's admission; it was not joined.`));
+          else console.log(pc.red(`The API no longer accepts this agent's admission; it was not joined. For a live grant with a retained key, retry the unchanged request with --recover-admission.`));
           return;
         }
         admission = { ...admission, verified: true, receipt: admissionReceipt };
@@ -3623,6 +3698,16 @@ export function registerSessionCommand(program) {
       }
 
       const remoteSession = verification.session || {};
+      let legacyAgentVerification = null;
+      if (namedLegacyAgent) {
+        legacyAgentVerification = await verifyLegacyAgentJoin(normalizedSessionId, {
+          agentId: resolvedAgentId, role, model, targetPath, remoteSession,
+        });
+        if (!legacyAgentVerification.ok) {
+          rejectLegacyJoin(legacyAgentVerification, resolvedAgentId);
+          return;
+        }
+      }
       const localSession = await ensureLocalSessionForRemoteCommand(normalizedSessionId, {
         targetPath,
         title: normalizeString(remoteSession.title),
@@ -3638,29 +3723,6 @@ export function registerSessionCommand(program) {
             )
           : { skipped: true, reason: "the grant does not include session.read" };
 
-      const acceptedOnboarding = normalizeSessionOnboarding(
-        invitationAcceptResult?.onboarding,
-        invitationAcceptResult?.claimedSeat,
-      );
-      const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
-      // An admitted join registers the admitted identity and nothing else. Otherwise an
-      // invitation's onboarding agent id is the identity only when none was given, and
-      // it is held to the same canonical rule before anything is registered locally.
-      if (!admission && !explicitAgent && acceptedAgentId) {
-        assertCanonicalAgentId(acceptedAgentId, "the invitation's agent id");
-      }
-      const agentSeed = admission ? admittedAgentId : explicitAgent || acceptedAgentId || legacyName;
-      const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
-      if (admission && resolvedAgentId !== admittedAgentId) {
-        throw new Error(`join would register "${resolvedAgentId}", not the admitted agent "${admittedAgentId}".`);
-      }
-      const roleWasExplicit = optionWasSetByCli(command, "role");
-      const role =
-        normalizeString(roleWasExplicit ? options.role : acceptedOnboarding?.role || options.role) ||
-        "coder";
-      const model = normalizeString(options.model) || "cli";
-      const hasConcreteAgentIdentity = Boolean(explicitAgent || acceptedAgentId);
-
       // Registration updates the local participant projection and returns
       // onboarding directly to this process. It never writes join, identity,
       // or coaching rows into the transcript.
@@ -3672,7 +3734,7 @@ export function registerSessionCommand(program) {
         clientKind: "cli",
         role,
         trackProcessExit: false,
-        awaitRemoteSync: hasConcreteAgentIdentity,
+        preserveIdentity: Boolean(admission || namedLegacyAgent),
       });
       const agentJoinRelayed = false;
       const localBriefingPayload =
@@ -3715,6 +3777,7 @@ export function registerSessionCommand(program) {
         materializedLocalSession: localSession.materialized,
         refreshedLocalSession: Boolean(localSession.refreshed),
         verificationSource: verification.source,
+        remoteAgentVerification: legacyAgentVerification,
         joinHydration,
         eventCount: Number.isFinite(eventCount) ? eventCount : 0,
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
@@ -5515,33 +5578,30 @@ export function registerSessionCommand(program) {
           );
         }
         if (existingListener.running && options.force) {
-          const stopMatchesResult = await stopMatchingListenerProcesses(normalizedSessionId, agentId);
-          if (!stopMatchesResult.ok) {
-            // The listener being replaced is known (a verified pid record or a scan moments
-            // ago), so stopping it and starting this one never adds a listener. Only the
-            // cleanup of extra copies is skipped, and that is said rather than assumed.
-            console.error(
-              pc.yellow(
-                `The local process check did not complete (${stopMatchesResult.reason}); replacing listener pid ${existingListener.pid} only. Other copies of this listener, if any, were not checked.`,
-              ),
+          // --force never stops a process this command runs under, and never on a guess:
+          // it refuses, and stops and starts nothing, unless the takeover scan confirms
+          // what it stops.
+          const refuseTakeover = ({ pid, reason }) =>
+            new Error(
+              reason === "ancestor_listener"
+                ? `A session listener is already running for session ${normalizedSessionId} as ${agentId} (pid ${pid}), and this command runs under it, so --force will not stop it. No listener was stopped or started. Stop that listener first, or use --allow-duplicate if you intentionally need more than one.`
+                : `Could not confirm that pid ${pid} is a session listener --force can replace for session ${normalizedSessionId} as ${agentId} (${reason}). No listener was stopped or started. Run the command again, or use --allow-duplicate to start without this check (it can then run alongside an existing listener).`,
             );
+          if (existingListener.ancestor) {
+            throw refuseTakeover({ pid: existingListener.pid, reason: "ancestor_listener" });
           }
-          const scannedStops = stopMatchesResult.ok ? stopMatchesResult.results : [];
-          const stoppedPids = new Set(
-            scannedStops
-              .filter((result) => result.stopped)
-              .map((result) => Number(result.pid)),
-          );
-          let explicitStopResult = null;
-          if (existingListener.pid && !stoppedPids.has(Number(existingListener.pid))) {
-            explicitStopResult = await requestListenerProcessStop(existingListener.pid);
+          const stopMatchesResult = await stopMatchingListenerProcesses(normalizedSessionId, agentId, {
+            listener: existingListener,
+          });
+          if (!stopMatchesResult.ok) {
+            // What the status check found may no longer hold, and an unread table cannot
+            // show which processes this command runs under, so nothing is stopped.
+            throw refuseTakeover({ pid: existingListener.pid, reason: stopMatchesResult.reason });
+          }
+          if (stopMatchesResult.refused) {
+            throw refuseTakeover(stopMatchesResult.refused);
           }
-          const failedStops = [
-            ...scannedStops.filter((result) => !result.stopped),
-            ...(explicitStopResult && !explicitStopResult.stopped
-              ? [{ pid: existingListener.pid, ...explicitStopResult }]
-              : []),
-          ];
+          const failedStops = stopMatchesResult.results.filter((result) => !result.stopped);
           if (failedStops.length > 0) {
             const failed = failedStops[0];
             throw new Error(

package/src/mcp/bridge-inputs.js

@@ -202,6 +202,9 @@ export const BRIDGE_DENIED_INPUTS = Object.freeze({
   "ring-owner": {
     gatewayUrl: "the gateway that receives the user's token",
   },
+  "session.join": {
+    recoverAdmission: "restores an agent credential using the delegator's retained private key; CLI control only",
+  },
   "swarm.create": {
     target: "the site that this plan tests",
   },