sentinelayer-cli 0.46.4 → 0.46.5

package/README.md

@@ -46,6 +46,22 @@ sl watch run-events --run-id <run-id>
 
 Windows PowerShell note: `sl` is a built-in alias for `Set-Location`. Use `sentinelayer-cli` (or short alias `slc`) instead.
 
+### Human sign-in and agent identity
+
+`sl auth login --skip-browser-open` prints the approval URL before waiting;
+in JSON mode the URL goes to stderr. A server outage during `auth status` is
+unavailable validation, not logout. Do not delete credential encryption keys
+or log out to repair a keyring/file-permission error.
+
+An admitted agent receives its own AIdenID email, Ed25519-backed passport and
+room-scoped credential after human approval. Its email and cryptographic
+identity remain visible on reconnect; email alone never grants access.
+An interrupted claim or missing credential can be recovered with the retained
+agent key. For a stale active credential, repeat the original join with
+`--recover-admission`, the same `--goal`, `--scope` and `--ttl`.
+Recovery requires API support, preserves the original expiry, and cannot revive
+revoked, stopped or expired permissions. It is not TTL renewal.
+
 ## MCP Live Entry Points And Incident Response
 
 Live MCP entry points:

package/package.json

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

package/src/auth/gate.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
 import { resolveActiveAuthSession } from "./service.js";
+import { readStoredSessionMetadata } from "./session-store.js";
 import { resolveAgentAdmissionTarget } from "../session/admission-auth.js";
 import { authLoginHint } from "../ui/command-hints.js";
 import { isAuthenticated } from "./credential-destinations.js";
@@ -378,7 +379,9 @@ export async function checkAuthGate(args) {
         resolveError = "session_invalid";
       }
     } else {
-      resolveError = "no_session";
+      // A keyring/decryption failure leaves the metadata intact. That is not
+      // absence, and recommending logout would destroy recoverable sign-in.
+      resolveError = (await readStoredSessionMetadata()) ? "session_token_missing" : "no_session";
     }
   } catch (error) {
     resolveError = error instanceof Error ? `session_read_error: ${error.message}` : "session_read_error";
@@ -405,15 +408,19 @@ export function printAuthRequired(failureReason = null) {
   if (reason === "session_expired") {
     console.error("  Your stored session has expired. Log in again:");
   } else if (reason === "session_token_missing") {
-    console.error("  Your session metadata is present but the token is missing");
-    console.error("  (likely a keyring read failure or mismatched storage).");
+    console.error("  Your session metadata is present but its credential cannot be read.");
+    console.error("  Check the current user/home, keyring, encryption key and file permissions.");
+    console.error("  Your stored credentials were not cleared; repair storage before signing in again.");
     console.error("");
-    console.error("  " + pc.yellow("Fix:") + " log out to clear the stale metadata, then log in:");
-    console.error("    " + pc.cyan("sentinelayer-cli auth logout"));
+    process.exitCode = 1;
+    return;
   } else if (reason && reason.startsWith("session_read_error")) {
     console.error("  Session read failed: " + pc.yellow(reason.replace(/^session_read_error:\s*/, "")));
-    console.error("  Log out and back in to reset local state:");
-    console.error("    " + pc.cyan("sentinelayer-cli auth logout"));
+    console.error("  Check the current user/home and credential-file permissions.");
+    console.error("  Your stored credentials were not cleared; do not log out to repair a read error.");
+    console.error("");
+    process.exitCode = 1;
+    return;
   } else {
     console.error("  Log in to SentinelLayer to use CLI commands:");
   }

package/src/auth/service.js

@@ -7,6 +7,7 @@ import open from "open";
 import { loadConfig } from "../config/service.js";
 import { scopedAdmissionAuth } from "./admission-scope.js";
 import {
+  CredentialDestinationRefused,
   DEFAULT_API_URL,
   assertTrustedApiUrl,
   credentialFor,
@@ -453,6 +454,7 @@ async function rotateStoredApiTokenIfNeeded({
       tokenPrefix: issued.token_prefix || null,
       tokenExpiresAt: issued.expires_at || null,
       user: session.user,
+      aidenid: session.aidenid,
     },
     { homeDir }
   );
@@ -490,7 +492,8 @@ async function rotateStoredApiTokenIfNeeded({
  *   tokenTtlDays?: number,
  *   ide?: string,
  *   cliVersion?: string,
- *   homeDir?: string
+ *   homeDir?: string,
+ *   onAuthorize?: (details: { authorizeUrl: string, browserOpened: boolean }) => void | Promise<void>
  * }} [options]
  * @returns {Promise<{
  *   apiUrl: string,
@@ -521,6 +524,7 @@ export async function loginAndPersistSession({
   ide = DEFAULT_IDE_NAME,
   cliVersion = "",
   homeDir,
+  onAuthorize = () => {},
 } = {}) {
   const apiUrl = await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir });
   // The token this flow issues is the user's, so the API that issues it must be the configured
@@ -548,6 +552,10 @@ export async function loginAndPersistSession({
     }
   }
 
+  // Headless hosts must receive the URL before approval polling can complete.
+  // The command renders this on stderr in JSON mode, keeping stdout parseable.
+  await onAuthorize({ authorizeUrl, browserOpened });
+
   const approval = await pollCliAuthSession({
     apiUrl,
     sessionId: String(session.session_id || "").trim(),
@@ -768,7 +776,8 @@ export async function resolveActiveAuthSession({
  *   homeDir?: string
  * }} [options]
  * @returns {Promise<{
- *   authenticated: boolean,
+ *   authenticated: boolean | null,
+ *   validation: "none" | "not_checked" | "verified" | "rejected" | "unavailable" | "storage_unavailable",
  *   apiUrl: string,
  *   source: string | null,
  *   storage: string | null,
@@ -805,20 +814,25 @@ export async function getAuthStatus({
   });
 
   if (!session) {
+    // Encrypted metadata can survive a missing/unreadable key or keyring.
+    // Distinguish recoverable storage from actual absence without creating a
+    // replacement key, validating remotely, or claiming authentication.
+    const stored = await readStoredSessionMetadata({ homeDir });
     return {
-      authenticated: false,
+      authenticated: stored ? null : false,
+      validation: stored ? "storage_unavailable" : "none",
       apiUrl: await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir }),
-      source: null,
-      storage: null,
-      user: null,
-      aidenid: null,
+      source: stored ? "storage_unknown" : null,
+      storage: stored?.storage || null,
+      user: stored ? normalizeUser(stored.user || {}) : null,
+      aidenid: stored?.aidenid || null,
       remoteUser: null,
       remoteError: null,
       rotated: false,
-      tokenExpiresAt: null,
-      tokenPrefix: null,
-      tokenId: null,
-      filePath: null,
+      tokenExpiresAt: stored?.tokenExpiresAt || null,
+      tokenPrefix: stored?.tokenPrefix || null,
+      tokenId: stored?.tokenId || null,
+      filePath: stored?.filePath || null,
     };
   }
 
@@ -829,12 +843,12 @@ export async function getAuthStatus({
       remoteUser = normalizeUser(await fetchCurrentUser({ apiUrl: session.apiUrl, credential: session.credential }));
     } catch (error) {
       remoteError =
-        error instanceof SentinelayerApiError
+        error instanceof SentinelayerApiError || error instanceof CredentialDestinationRefused
           ? {
               code: error.code,
               message: error.message,
-              status: error.status,
-              requestId: error.requestId,
+              status: error instanceof CredentialDestinationRefused ? 403 : error.status,
+              requestId: error.requestId || null,
             }
           : {
               code: "UNKNOWN",
@@ -845,8 +859,13 @@ export async function getAuthStatus({
     }
   }
 
+  const validationUnavailable = remoteError && (
+    [408, 425, 429, 499].includes(remoteError.status) || remoteError.status >= 500
+  );
   return {
-    authenticated: !remoteError,
+    // Unknown remote health is neither a successful validation nor a logout.
+    authenticated: validationUnavailable ? null : !remoteError,
+    validation: validationUnavailable ? "unavailable" : remoteError ? "rejected" : checkRemote ? "verified" : "not_checked",
     apiUrl: session.apiUrl,
     source: session.source,
     storage: session.storage,

package/src/auth/session-store.js

@@ -135,60 +135,68 @@ function resolveLegacyCredentialsKeyPath({ homeDir } = {}) {
   return path.join(resolvedHome, ".sentinelayer", "credentials.key");
 }
 
-async function loadOrCreateFileKey({ homeDir } = {}) {
-  const keyPath = resolveCredentialsKeyPath({ homeDir });
-  const legacyKeyPath = resolveLegacyCredentialsKeyPath({ homeDir });
-  try {
-    const raw = await fsp.readFile(keyPath, "utf-8");
-    const key = Buffer.from(String(raw || "").trim(), "base64");
-    if (key.length === 32) {
-      return key;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
+async function readFileKeyAt(keyPath) {
+  // Exclusive-create fallback filesystems may expose a partially written key.
+  // Retry that bounded race, but never replace an invalid or unreadable key.
+  for (let attempt = 0; ; attempt += 1) {
+    let raw;
+    try {
+      raw = await fsp.readFile(keyPath, "utf-8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
       throw error;
     }
-  }
-
-  try {
-    const legacyRaw = await fsp.readFile(legacyKeyPath, "utf-8");
-    const legacyKey = Buffer.from(String(legacyRaw || "").trim(), "base64");
-    if (legacyKey.length === 32) {
-      await fsp.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
-      await fsp.writeFile(keyPath, legacyKey.toString("base64"), { encoding: "utf-8", mode: 0o600 });
-      try {
-        await fsp.chmod(keyPath, 0o600);
-      } catch {
-        // Windows does not reliably support POSIX chmod semantics.
-      }
-      let verified = false;
-      try {
-        const verifyRaw = await fsp.readFile(keyPath, "utf-8");
-        const verifyKey = Buffer.from(String(verifyRaw || "").trim(), "base64");
-        verified = verifyKey.length === 32 && verifyKey.equals(legacyKey);
-      } catch {
-        verified = false;
-      }
-      if (verified) {
-        await fsp.rm(legacyKeyPath, { force: true });
-      }
-      return legacyKey;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
+    const encoded = String(raw || "").trim();
+    const key = Buffer.from(encoded, "base64");
+    if (key.length === 32 && key.toString("base64") === encoded) return key;
+    if (attempt >= 5) {
+      const error = new Error("Stored credential encryption key is invalid; it was not replaced.");
+      error.code = "CREDENTIALS_KEY_INVALID";
       throw error;
     }
+    await delayMilliseconds(20);
   }
+}
+
+async function readFileKey({ homeDir } = {}) {
+  return (await readFileKeyAt(resolveCredentialsKeyPath({ homeDir }))) ||
+    (await readFileKeyAt(resolveLegacyCredentialsKeyPath({ homeDir })));
+}
 
-  const key = crypto.randomBytes(32);
+async function loadOrCreateFileKey({ homeDir } = {}) {
+  const keyPath = resolveCredentialsKeyPath({ homeDir });
+  const existing = await readFileKeyAt(keyPath);
+  if (existing) return existing;
+  const legacyKey = await readFileKeyAt(resolveLegacyCredentialsKeyPath({ homeDir }));
+  const key = legacyKey || crypto.randomBytes(32);
+  const encoded = key.toString("base64");
   await fsp.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
-  await fsp.writeFile(keyPath, key.toString("base64"), { encoding: "utf-8", mode: 0o600 });
+  const tmpPath = `${keyPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
   try {
-    await fsp.chmod(keyPath, 0o600);
-  } catch {
-    // Windows does not reliably support POSIX chmod semantics.
+    await fsp.writeFile(tmpPath, encoded, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+    await syncFile(tmpPath);
+    try {
+      // Publish complete bytes once. Every concurrent writer then uses the winner.
+      await fsp.link(tmpPath, keyPath);
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        if (!["ENOTSUP", "ENOSYS", "EXDEV", "EPERM"].includes(error?.code)) throw error;
+        try {
+          await fsp.writeFile(keyPath, encoded, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+        } catch (fallbackError) {
+          if (fallbackError?.code !== "EEXIST") throw fallbackError;
+        }
+      }
+    }
+    const persisted = await readFileKeyAt(keyPath);
+    if (!persisted) throw new Error("Credential encryption key could not be persisted.");
+    await syncFile(keyPath);
+    await syncDirectory(path.dirname(keyPath));
+    // Keep the legacy key: deleting it can race a read-only legacy reader.
+    return persisted;
+  } finally {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
   }
-  return key;
 }
 
 function encryptToken(token, key) {
@@ -540,7 +548,11 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
     return null;
   }
   try {
-    const key = await loadOrCreateFileKey({ homeDir });
+    const key = await readFileKey({ homeDir });
+    if (!key) {
+      emitSessionWarning("FILE_CREDENTIAL_UNAVAILABLE", { reason: "key_missing", source: "file-encrypted" });
+      return null;
+    }
     const token = decryptToken(
       {
         tokenEncrypted: metadata.tokenEncrypted,
@@ -550,7 +562,13 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
       key
     );
     return token || null;
-  } catch {
+  } catch (error) {
+    emitSessionWarning("FILE_CREDENTIAL_UNAVAILABLE", {
+      reason: error?.code === "EACCES" || error?.code === "EPERM"
+        ? "key_unreadable"
+        : error?.code === "CREDENTIALS_KEY_INVALID" ? "key_invalid" : "decryption_failed",
+      source: "file-encrypted",
+    });
     return null;
   }
 }
@@ -722,6 +740,7 @@ export async function readStoredSessionMetadata({ homeDir } = {}) {
  *   tokenPrefix?: string | null,
  *   tokenExpiresAt?: string | null,
  *   user?: Record<string, unknown>
+ *   aidenid?: Record<string, unknown> | null
  * }} [session]
  * @param {{ homeDir?: string }} [options]
  * @returns {Promise<{
@@ -754,6 +773,7 @@ export async function writeStoredSession(
     tokenPrefix = null,
     tokenExpiresAt = null,
     user = {},
+    aidenid = null,
   } = {},
   { homeDir } = {}
 ) {
@@ -778,6 +798,7 @@ export async function writeStoredSession(
     tokenPrefix,
     tokenExpiresAt,
     user: normalizeUser(user),
+    aidenid,
     createdAt: existingMetadata?.createdAt || updatedAt,
     updatedAt,
   });

package/src/commands/auth.js

@@ -133,6 +133,14 @@ export function registerAuthCommand(program) {
           tokenLabel: options.tokenLabel,
           tokenTtlDays,
           cliVersion: CLI_VERSION,
+          onAuthorize: ({ authorizeUrl }) => {
+            // A spawned opener does not prove a browser exists on a headless host.
+            if (!authorizeUrl) return;
+            const safeUrl = String(authorizeUrl).replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 4096);
+            const line = `Open this URL to approve sign-in:\n${safeUrl}\n`;
+            if (shouldEmitJson(options, command)) process.stderr.write(line);
+            else console.log(line.trimEnd());
+          },
         });
       } catch (error) {
         throw new Error(formatApiError(error));
@@ -159,10 +167,6 @@ export function registerAuthCommand(program) {
       if (result.filePath) {
         console.log(pc.gray(`Session metadata: ${result.filePath}`));
       }
-      if (!result.browserOpened && result.authorizeUrl) {
-        console.log(pc.yellow("Open this URL to approve sign-in:"));
-        console.log(result.authorizeUrl);
-      }
     });
 
   auth
@@ -199,6 +203,13 @@ export function registerAuthCommand(program) {
 
       console.log(pc.bold("Authentication status"));
       console.log(pc.gray(`API: ${status.apiUrl}`));
+      if (status.validation === "storage_unavailable") {
+        console.log(pc.yellow("Stored sign-in metadata exists, but its credential cannot be read. Authentication is unknown."));
+        if (status.filePath) console.log(pc.gray(`Session metadata: ${status.filePath}`));
+        console.log(pc.gray("Check the current user/home, keyring availability, encryption key and file permissions."));
+        console.log(pc.gray("Credentials were not cleared. Repair storage instead of logging out or signing in again for this error."));
+        return;
+      }
       if (!status.source) {
         console.log(pc.yellow("No active session token found."));
         printAuthHint();
@@ -254,6 +265,15 @@ export function registerAuthCommand(program) {
             }`
           )
         );
+        if (status.validation === "unavailable") {
+          console.log(pc.yellow("Remote validation is temporarily unavailable; your existing credentials were not cleared."));
+          console.log(pc.gray("Retry auth status when the API is reachable. Do not sign in again solely for this validation error."));
+          return;
+        }
+        if (["CREDENTIAL_DESTINATION_REFUSED", "CREDENTIAL_PATH_REFUSED"].includes(status.remoteError.code)) {
+          console.log(pc.yellow("Credential destination was refused. Check the configured API; signing in again does not change this boundary."));
+          return;
+        }
       } else {
         console.log(pc.yellow("Remote validation was skipped (`--offline`)."));
       }

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,
@@ -3437,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);
@@ -3455,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,
@@ -3473,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;
@@ -3491,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,
@@ -3508,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 }) => {
@@ -3523,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.
@@ -3550,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
@@ -3564,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 = {
@@ -3594,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 };
@@ -3622,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),
@@ -3637,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.
@@ -3671,7 +3734,7 @@ export function registerSessionCommand(program) {
         clientKind: "cli",
         role,
         trackProcessExit: false,
-        awaitRemoteSync: hasConcreteAgentIdentity,
+        preserveIdentity: Boolean(admission || namedLegacyAgent),
       });
       const agentJoinRelayed = false;
       const localBriefingPayload =
@@ -3714,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,

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",
   },

package/src/session/admission.js

@@ -60,9 +60,18 @@ export const CLAIM_FIELDS = Object.freeze([
   "keyThumbprint",
   "nonce",
 ]);
+export const RECOVERY_DOMAIN = "sentinelayer.admission.recover.v1";
+export const RECOVERY_FIELDS = Object.freeze([
+  "admissionId", "sessionId", "agentId", "delegatorUserId", "publicKey",
+  "keyThumbprint", "grantId", "goalDigest", "actions", "policyVersion",
+  "expiresAt", "nonce", "challengeExpiresAt", "tenantUserId", "passportId",
+  "aidenidIdentityId", "aidenidHandle",
+]);
 const ROUTE = {
   request: "POST /api/v1/sessions/{session_id}/admissions",
   claim: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/claim",
+  recoverChallenge: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/recover/challenge",
+  recover: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/recover",
   cancel: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/cancel",
 };
 // Final admission statuses: polling stops, nothing is claimed, local request state is cleared.
@@ -402,6 +411,155 @@ async function mutate(auth, sessionId, routeId, url, body, { requestMutation, op
   });
 }
 
+// Recovery rotates only an ACTIVE credential. It never extends a permission or
+// signs the old claim domain, and it needs both the human connection and this
+// agent's own retained private key. A lost response can be recovered again with
+// another fresh server challenge; plaintext credentials are never redelivered.
+async function recoverCredential(auth, sid, agent, admissionId, key, deps, now) {
+  const challenge = await mutate(
+    auth, sid, ROUTE.recoverChallenge,
+    admissionMemberUrl(auth.apiUrl, sid, admissionId, "/recover/challenge"), {},
+    { ...deps, operationName: "session.admission_recovery_challenge" }
+  );
+  const fields = challenge?.recovery?.preimage;
+  const advertised = challenge?.recovery?.fields;
+  if (
+    challenge?.status !== "active" || challenge.admissionId !== admissionId ||
+    challenge?.recovery?.domain !== RECOVERY_DOMAIN || !fields ||
+    !Array.isArray(advertised) || advertised.length !== RECOVERY_FIELDS.length ||
+    [...advertised].sort().join("\0") !== [...RECOVERY_FIELDS].sort().join("\0") ||
+    fields.admissionId !== admissionId || fields.sessionId !== sid ||
+    fields.agentId !== agent || fields.publicKey !== key.publicKey ||
+    !normalizeString(fields.aidenidIdentityId) || !normalizeString(fields.aidenidHandle) ||
+    !Array.isArray(fields.actions) || !fields.actions.length ||
+    fields.actions.some((action) => !ADMISSION_ACTIONS.includes(action)) ||
+    !Number.isSafeInteger(fields.expiresAt) || fields.expiresAt * 1000 <= now() ||
+    !Number.isSafeInteger(fields.challengeExpiresAt) || fields.challengeExpiresAt * 1000 <= now()
+  ) {
+    throw new Error("Refusing to sign: invalid or mismatched admission recovery challenge.");
+  }
+  const signature = signBytes(null, canonicalPreimage(fields, {
+    domain: RECOVERY_DOMAIN, fields: [...RECOVERY_FIELDS],
+  }), key.privateKey);
+  const recovered = await mutate(
+    auth, sid, ROUTE.recover,
+    admissionMemberUrl(auth.apiUrl, sid, admissionId, "/recover"),
+    { nonce: fields.nonce, signature: signature.toString("base64url") },
+    { ...deps, operationName: "session.admission_recover" }
+  );
+  if (
+    recovered?.status !== "active" || recovered.admissionId !== admissionId ||
+    recovered?.grant?.sessionId !== sid || recovered.grant.grantId !== fields.grantId ||
+    recovered.grant.expiresAt !== fields.expiresAt ||
+    recovered.grant.goalDigest !== fields.goalDigest ||
+    !Array.isArray(recovered.grant.actions) ||
+    [...recovered.grant.actions].sort().join("\0") !== [...fields.actions].sort().join("\0") ||
+    recovered?.identity?.keyThumbprint !== fields.keyThumbprint ||
+    recovered.identity.passportId !== fields.passportId ||
+    recovered.identity.email?.address !== fields.aidenidHandle
+  ) {
+    throw new Error("Recovered admission does not match the unchanged signed authority.");
+  }
+  return recovered;
+}
+
+/** Serialize credential rotation AND publication across CLI processes.
+ * No age-based lock stealing: an API call may still commit after a local timer
+ * expires. Unknown/crashed owners fail explicitly without changing identity.
+ */
+export async function withAdmissionCredentialLock(filePath, run, { timeoutMs = 180_000 } = {}) {
+  const lockPath = `${filePath}.recovery-lock`;
+  await fsp.mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + timeoutMs;
+  let handle;
+  for (;;) {
+    try {
+      handle = await fsp.open(lockPath, "wx", 0o600);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) {
+        throw new Error(`Agent credential recovery is already locked at ${lockPath}. ` +
+          "Wait for the other join; if its process crashed, verify it has stopped before removing only this lock file. Human sign-in and the agent key were not changed.");
+      }
+      await sleepMs(25);
+    }
+  }
+  try {
+    await handle.writeFile(JSON.stringify({ pid: process.pid, host: os.hostname(), createdAt: new Date().toISOString() }));
+    return await run();
+  } finally {
+    await handle.close();
+    await fsp.unlink(lockPath);
+  }
+}
+
+async function recoverAndStore(auth, sid, agent, admissionId, key, fingerprint, deps, homeDir, now, rejectedToken = null) {
+  return withAdmissionCredentialLock(admissionCredentialPath(sid, agent, { homeDir }), async () => {
+    // Another process may have completed recovery while this process waited.
+    const current = await readAdmissionCredentialState(sid, agent, { homeDir, now: now() });
+    if (current.state === "live" && current.credential.admissionId === admissionId &&
+        current.credential.requestFingerprint === fingerprint && current.credential.publicKey === key.publicKey &&
+        current.credential.apiUrl === auth.apiUrl && current.credential.token !== rejectedToken) {
+      return redacted({ status: "active", reused: true, stored: current.credential, sid, agent, homeDir });
+    }
+    const claimed = await recoverCredential(auth, sid, agent, admissionId, key, deps, now);
+    const stored = await storeClaimedCredential(claimed, { auth, sid, agent, key, fingerprint, homeDir, now });
+    return { ...redacted({ status: "active", reused: true, stored, claimed, sid, agent, homeDir }), recovered: true };
+  });
+}
+
+async function storeClaimedCredential(claimed, { auth, sid, agent, key, fingerprint, homeDir, now }) {
+  if (!String(claimed?.credential?.token || "").startsWith("sladm_")) {
+    throw new Error("Admission did not return a scoped agent credential.");
+  }
+  const identity = identityMetadata(claimed.identity);
+  const grant = grantMetadata(claimed.grant);
+  const previous = await readAdmissionCredentialState(sid, agent, { homeDir, now: now() });
+  if (previous.state === "live" && previous.credential.admissionId === claimed.admissionId &&
+      previous.credential.publicKey === key.publicKey && previous.credential.apiUrl === auth.apiUrl &&
+      previous.credential.identity?.passportId === identity.passportId &&
+      previous.credential.identity?.keyThumbprint === identity.keyThumbprint &&
+      previous.credential.grant?.grantId === grant.grantId && previous.credential.expiresAt === grant.expiresAt) {
+    // Recovery does not reissue signed documents. Retain original documents
+    // only for this exact unchanged identity/grant; never synthesize new ones.
+    identity.passport ??= previous.credential.identity.passport;
+    grant.document ??= previous.credential.grant.document;
+  }
+  const stored = {
+    version: 3, sessionId: sid, agentId: agent, apiUrl: auth.apiUrl,
+    publicKey: key.publicKey, requestFingerprint: fingerprint,
+    admissionId: claimed.admissionId, token: claimed.credential.token,
+    expiresAt: claimed.grant.expiresAt, grantedActions: claimed.grant.actions,
+    passportId: claimed.identity.passportId, subject: claimed.identity.subject,
+    // Non-secret identity metadata survives reconnects. Email is never used as
+    // authentication: the credential/key binding remains the authority.
+    identity,
+    grant,
+    correlation: claimed.correlation,
+    storedAt: new Date(now()).toISOString(),
+  };
+  await writeSecretFile(admissionCredentialPath(sid, agent, { homeDir }), stored);
+  return stored;
+}
+
+function identityMetadata(identity) {
+  return {
+    subject: identity.subject, passportId: identity.passportId,
+    passportStatus: identity.passportStatus, keyThumbprint: identity.keyThumbprint,
+    popAssurance: identity.popAssurance,
+    email: identity.email && { status: identity.email.status, address: identity.email.address },
+    passport: identity.passport,
+  };
+}
+
+function grantMetadata(grant) {
+  return {
+    grantId: grant.grantId, sessionId: grant.sessionId, actions: grant.actions,
+    expiresAt: grant.expiresAt, goalDigest: grant.goalDigest, document: grant.document,
+  };
+}
+
 /**
  * Request admission, wait for a human decision, and claim the grant.
  * Returns a REDACTED result: the credential token is never included.
@@ -419,6 +577,7 @@ export async function runAdmissionJoin(
     actions = DEFAULT_ADMISSION_ACTIONS,
     ttlSeconds = 7200,
     wait = true,
+    recoverActive = false,
     waitTimeoutMs = 15 * 60_000,
     targetPath = process.cwd(),
     homeDir,
@@ -464,9 +623,19 @@ export async function runAdmissionJoin(
   // same key. A different goal, scope or duration is a question for the server,
   // which answers with the existing grant (same purpose) or a conflict (new one).
   const held = await readAdmissionCredentialState(sid, agent, { homeDir, now: now() });
-  if (held.state === "live" && held.credential.requestFingerprint === fingerprint) {
+  if (!recoverActive && held.state === "live" && held.credential.requestFingerprint === fingerprint) {
     return redacted({ status: "active", reused: true, stored: held.credential, sid, agent, homeDir });
   }
+  if (recoverActive && held.credential?.admissionId) {
+    if (held.credential.requestFingerprint !== fingerprint || held.credential.publicKey !== key.publicKey ||
+        held.credential.apiUrl !== auth.apiUrl) {
+      throw new Error("Credential recovery requires the unchanged agent key, API, goal, scope and TTL.");
+    }
+    // Go directly to recovery, never file a new request after a refused cached
+    // bearer. A revoked/expired grant must be refused, not reopened as pending.
+    return recoverAndStore(auth, sid, agent, held.credential.admissionId, key, fingerprint, deps, homeDir, now,
+      held.credential.token);
+  }
 
   const statePath = admissionStatePath(targetPath, sid, agent);
   let state = await readJsonFile(statePath);
@@ -501,6 +670,7 @@ export async function runAdmissionJoin(
     if (
       created?.status === "active" &&
       created?.reused &&
+      !recoverActive &&
       held.state === "live" &&
       held.credential.admissionId === created.admissionId
     ) {
@@ -508,12 +678,10 @@ export async function runAdmissionJoin(
       return redacted({ status: "active", reused: true, stored: held.credential, sid, agent, homeDir });
     }
     if (created?.status === "active" && created?.reused) {
-      // The server already holds a live grant for this key, but we have no stored
-      // credential for it (e.g. a different machine). It cannot be re-issued.
-      throw new Error(
-        "This agent already holds an active admission here, but no credential is stored " +
-          "on this machine. Ask the room owner to revoke it, then join again."
-      );
+      const recovered = await recoverAndStore(auth, sid, agent, created.admissionId, key, fingerprint, deps, homeDir, now,
+        recoverActive && held.state === "live" ? held.credential.token : null);
+      await fsp.rm(statePath, { force: true });
+      return recovered;
     }
     state = {
       admissionId: created.admissionId,
@@ -590,46 +758,53 @@ export async function runAdmissionJoin(
     return { status: polled.status, admissionId: state.admissionId, waited: true };
   }
   if (polled.status === "active") {
-    throw new Error("Admission is already active but this machine holds no credential for it.");
-  }
-
-  const fields = polled?.claim?.preimage;
-  if (!fields || polled.claim.domain !== CLAIM_DOMAIN) {
-    throw new Error("Approved admission did not include a valid claim challenge.");
-  }
-  // Never sign a claim for a key or agent that is not ours.
-  if (fields.publicKey !== key.publicKey || fields.agentId !== agent || fields.sessionId !== sid) {
-    throw new Error("Refusing to sign: the claim challenge does not name this agent's key.");
+    const recovered = await recoverAndStore(auth, sid, agent, state.admissionId, key, fingerprint, deps, homeDir, now,
+      recoverActive && held.state === "live" ? held.credential.token : null);
+    await fsp.rm(statePath, { force: true });
+    return recovered;
   }
-  const signature = signBytes(null, canonicalPreimage(fields, { domain: CLAIM_DOMAIN, fields: [...CLAIM_FIELDS] }), key.privateKey);
-  const claimed = await mutate(
-    auth,
-    sid,
-    ROUTE.claim,
-    admissionMemberUrl(auth.apiUrl, sid, state.admissionId, "/claim"),
-    { nonce: fields.nonce, signature: signature.toString("base64url") },
-    { ...deps, operationName: "session.admission_claim" }
-  );
 
-  const stored = {
-    version: 2,
-    sessionId: sid,
-    agentId: agent,
-    // The credential is only ever sent to the API that issued it.
-    apiUrl: auth.apiUrl,
-    publicKey: key.publicKey,
-    requestFingerprint: fingerprint,
-    admissionId: claimed.admissionId,
-    token: claimed.credential.token,
-    expiresAt: claimed.grant.expiresAt,
-    grantedActions: claimed.grant.actions,
-    passportId: claimed.identity.passportId,
-    subject: claimed.identity.subject,
-    storedAt: new Date(now()).toISOString(),
-  };
-  await writeSecretFile(admissionCredentialPath(sid, agent, { homeDir }), stored);
+  // Initial claim is a credential writer too. The same cross-process lock must
+  // cover it through publication, or a delayed first claim could overwrite a
+  // recovered replacement. Refresh the nonce only after obtaining this lock.
+  const result = await withAdmissionCredentialLock(admissionCredentialPath(sid, agent, { homeDir }), async () => {
+    const current = await readAdmissionCredentialState(sid, agent, { homeDir, now: now() });
+    if (current.state === "live" && current.credential.admissionId === state.admissionId &&
+        current.credential.requestFingerprint === fingerprint && current.credential.publicKey === key.publicKey &&
+        current.credential.apiUrl === auth.apiUrl) {
+      return redacted({ status: "active", reused: true, stored: current.credential, sid, agent, homeDir });
+    }
+    const fresh = await checkedTransport(requestRead)(admissionMemberUrl(auth.apiUrl, sid, state.admissionId), {
+      method: "GET", credential: auth.credential,
+    });
+    if (TERMINAL.has(fresh.status)) {
+      return { status: fresh.status, admissionId: state.admissionId, waited: true };
+    }
+    if (fresh.status === "active") {
+      const recovered = await recoverCredential(auth, sid, agent, state.admissionId, key, deps, now);
+      const stored = await storeClaimedCredential(recovered, { auth, sid, agent, key, fingerprint, homeDir, now });
+      return { ...redacted({ status: "active", reused: true, stored, claimed: recovered, sid, agent, homeDir }), recovered: true };
+    }
+    const fields = fresh?.claim?.preimage;
+    if (fresh.status !== "approved" || fresh.identityReady === false || !fields || fresh.claim.domain !== CLAIM_DOMAIN) {
+      throw new Error("Approved admission did not include a valid claim challenge.");
+    }
+    if (fields.publicKey !== key.publicKey || fields.agentId !== agent || fields.sessionId !== sid ||
+        fields.admissionId !== state.admissionId) {
+      throw new Error("Refusing to sign: the claim challenge does not name this agent's key.");
+    }
+    const signature = signBytes(null, canonicalPreimage(fields, { domain: CLAIM_DOMAIN, fields: [...CLAIM_FIELDS] }), key.privateKey);
+    const claimed = await mutate(
+      auth, sid, ROUTE.claim,
+      admissionMemberUrl(auth.apiUrl, sid, state.admissionId, "/claim"),
+      { nonce: fields.nonce, signature: signature.toString("base64url") },
+      { ...deps, operationName: "session.admission_claim" }
+    );
+    const stored = await storeClaimedCredential(claimed, { auth, sid, agent, key, fingerprint, homeDir, now });
+    return redacted({ status: "active", reused: false, stored, claimed, sid, agent, homeDir });
+  });
   await fsp.rm(statePath, { force: true });
-  return redacted({ status: "active", reused: false, stored, claimed, sid, agent, homeDir });
+  return result;
 }
 
 function redacted({ status, reused, stored, claimed, sid, agent, homeDir }) {
@@ -637,28 +812,9 @@ function redacted({ status, reused, stored, claimed, sid, agent, homeDir }) {
     status,
     reused,
     admissionId: stored.admissionId,
-    identity: claimed
-      ? {
-          subject: claimed.identity.subject,
-          passportId: claimed.identity.passportId,
-          passportStatus: claimed.identity.passportStatus,
-          keyThumbprint: claimed.identity.keyThumbprint,
-          popAssurance: claimed.identity.popAssurance,
-          email: claimed.identity.email,
-          passport: claimed.identity.passport,
-        }
-      : { subject: stored.subject, passportId: stored.passportId },
-    grant: claimed
-      ? {
-          grantId: claimed.grant.grantId,
-          sessionId: claimed.grant.sessionId,
-          actions: claimed.grant.actions,
-          expiresAt: claimed.grant.expiresAt,
-          goalDigest: claimed.grant.goalDigest,
-          document: claimed.grant.document,
-        }
-      : { sessionId: sid, actions: stored.grantedActions, expiresAt: stored.expiresAt },
-    correlation: claimed ? claimed.correlation : { actorRef: `adm:${stored.admissionId}` },
+    identity: stored.identity || (claimed ? identityMetadata(claimed.identity) : { subject: stored.subject, passportId: stored.passportId }),
+    grant: stored.grant || (claimed ? grantMetadata(claimed.grant) : { sessionId: sid, actions: stored.grantedActions, expiresAt: stored.expiresAt }),
+    correlation: claimed ? claimed.correlation : stored.correlation || { actorRef: `adm:${stored.admissionId}` },
     jev: claimed ? claimed.jev : undefined,
     // A reference only. The token itself never appears in output.
     credential: { storage: admissionCredentialPath(sid, agent, { homeDir }), redacted: true },

package/src/session/agent-access.js

@@ -0,0 +1,137 @@
+import process from "node:process";
+
+import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
+import { requestJson, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { urlPathSegment } from "../net/url-path.js";
+import { readAdmissionCredentialState } from "./admission.js";
+import { assertCanonicalAgentId, currentAdmittedAgent } from "./admission-auth.js";
+
+const GRANT_ROLES = new Set(["auditor", "coder", "coordinator", "observer", "orchestrator", "reviewer"]);
+const MAX_GRANT_PAGES = 20;
+const PAGE_LIMIT = 100;
+
+function refused(code, reason, status = null) {
+  return { ok: false, code, reason, status, source: "legacy_grant_presence" };
+}
+
+/** A stored admission is never permission to enter the human-account legacy path. */
+export async function legacyJoinAdmissionRefusal(sessionId, agentId, {
+  homeDir,
+  readAdmissionState = readAdmissionCredentialState,
+} = {}) {
+  if (currentAdmittedAgent()) return refused("ADMISSION_CREDENTIAL_REFUSED", "admitted_context");
+  let held;
+  try {
+    held = await readAdmissionState(sessionId, agentId, { homeDir });
+  } catch {
+    return refused("ADMISSION_CREDENTIAL_REFUSED", "admission_lookup_unavailable");
+  }
+  if (held?.state === "none") return null;
+  return held?.state === "live"
+    ? refused("ADMISSION_REQUIRED", "stored_admission_requires_scoped_join")
+    : refused("ADMISSION_CREDENTIAL_REFUSED", held?.reason || "admission_lookup_unavailable");
+}
+
+/**
+ * Verify an existing account-bound legacy grant and its room-scoped presence.
+ * Never POST /agent-grants: GET lists active grants only, whereas POST reactivates
+ * revoked grants. Absence therefore cannot safely authorize an automatic grant.
+ * No transcript event, email or cryptographic identity is minted here.
+ */
+export async function verifyLegacyAgentJoin(sessionId, {
+  agentId,
+  role = "coder",
+  model = "cli",
+  targetPath = process.cwd(),
+  homeDir,
+  remoteSession = {},
+  timeoutMs = 10_000,
+  now = () => Date.now(),
+  readAdmissionState = readAdmissionCredentialState,
+  resolveAuthSession = resolveActiveAuthSession,
+  requestRead = requestJson,
+  requestMutation = requestJsonMutation,
+} = {}) {
+  const sid = String(sessionId || "").trim();
+  const agent = String(agentId || "").trim().toLowerCase();
+  const requestedRole = String(role || "").trim().toLowerCase();
+  try {
+    assertCanonicalAgentId(agent, "legacy join agent");
+    if (!sid || !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent) || agent.startsWith("human-") || ["cli-user", "unknown"].includes(agent)) {
+      return refused("LEGACY_AGENT_ID_INVALID", "ungrantable_agent");
+    }
+    if (!GRANT_ROLES.has(requestedRole)) return refused("LEGACY_GRANT_ROLE_MISMATCH", "unsupported_role");
+    if (remoteSession.agentAdmissionMode && remoteSession.agentAdmissionMode !== "legacy") {
+      return refused("ADMISSION_REQUIRED", "room_requires_admission");
+    }
+    const admissionOptions = { homeDir, readAdmissionState };
+    let refusal = await legacyJoinAdmissionRefusal(sid, agent, admissionOptions);
+    if (refusal) return refusal;
+    const auth = await resolveAuthSession({ cwd: targetPath, env: process.env, homeDir, autoRotate: false });
+    if (!isAuthenticated(auth)) return refused("AUTH_REQUIRED", "not_authenticated", 401);
+    if (auth.source === "session_admission") return refused("ADMISSION_CREDENTIAL_REFUSED", "admitted_context");
+    const credential = await credentialFor(auth);
+    const apiUrl = String(auth.apiUrl || "").replace(/\/+$/, "");
+    const deadline = now() + Math.max(1, Math.min(Number(timeoutMs) || 10_000, 30_000));
+    const remaining = () => Math.max(0, deadline - now());
+    let after = "";
+    let grant;
+    for (let page = 0; page < MAX_GRANT_PAGES; page += 1) {
+      refusal = await legacyJoinAdmissionRefusal(sid, agent, admissionOptions);
+      if (refusal) return refusal;
+      if (!remaining()) return refused("LEGACY_GRANT_UNAVAILABLE", "verification_timeout");
+      const query = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+      if (after) query.set("after", after);
+      const result = await checkedTransport(requestRead)(`${apiUrl}/api/v1/sessions/agent-grants?${query}`, {
+        method: "GET", credential, timeoutMs: remaining(), maxRetries: 0,
+      });
+      if (!Array.isArray(result?.grants) || result.grants.length > PAGE_LIMIT) {
+        return refused("LEGACY_GRANT_CONTRACT_MISMATCH", "invalid_grant_page");
+      }
+      const matches = result.grants.filter((item) => item?.agentId === agent);
+      if (matches.length > 1) return refused("LEGACY_GRANT_CONTRACT_MISMATCH", "duplicate_grant_identity");
+      if (matches.length) { grant = matches[0]; break; }
+      if (result.nextAfter === null) return refused("LEGACY_GRANT_NOT_ACTIVE", "missing_or_revoked");
+      const next = result.nextAfter;
+      if (typeof next !== "string" || !next || next <= after || !result.grants.some((item) => item?.agentId === next)) {
+        return refused("LEGACY_GRANT_CONTRACT_MISMATCH", "invalid_grant_cursor");
+      }
+      after = next;
+    }
+    if (!grant) return refused("LEGACY_GRANT_UNAVAILABLE", "grant_page_limit");
+    if (grant.exists === false || grant.revoked === true || grant.revokedAt != null) {
+      return refused("LEGACY_GRANT_NOT_ACTIVE", "missing_or_revoked");
+    }
+    if (grant.exists !== true || grant.revoked !== false || grant.revokedAt !== null || typeof grant.id !== "string" || !grant.id) {
+      return refused("LEGACY_GRANT_CONTRACT_MISMATCH", "invalid_grant_confirmation");
+    }
+    if (grant.role !== requestedRole) return refused("LEGACY_GRANT_ROLE_MISMATCH", "requested_role_not_granted");
+    refusal = await legacyJoinAdmissionRefusal(sid, agent, admissionOptions);
+    if (refusal) return refusal;
+    if (!remaining()) return refused("LEGACY_PRESENCE_UNAVAILABLE", "verification_timeout");
+    const presence = await checkedTransport(requestMutation)(
+      `${apiUrl}/api/v1/sessions/${urlPathSegment(sid, { label: "sessionId" })}/presence`, {
+        method: "PUT", operationName: "session.legacy_join_presence", credential,
+        timeoutMs: remaining(), maxRetries: 0,
+        body: { agentId: agent, state: "idle", model, clientKind: "cli", observedAt: new Date(now()).toISOString() },
+      },
+    );
+    if (presence?.agentId !== agent) return refused("LEGACY_PRESENCE_CONTRACT_MISMATCH", "presence_identity_mismatch");
+    if (presence.status !== "ok" || presence.recorded !== true || !Number.isFinite(presence.ttlSeconds) || presence.ttlSeconds <= 0) {
+      return refused("LEGACY_PRESENCE_UNAVAILABLE", "presence_not_recorded");
+    }
+    return {
+      ok: true, source: "legacy_grant_presence",
+      grant: { id: grant.id, agentId: grant.agentId, role: grant.role },
+      presence: { recorded: true, agentId: agent, ttlSeconds: presence.ttlSeconds },
+    };
+  } catch (error) {
+    const status = Number(error?.status) || null;
+    const code = error?.code;
+    if (code === "ADMISSION_REQUIRED" || code === "ADMISSION_SCOPE_DENIED") return refused(code, "admission_required_or_refused", status);
+    if (status === 401) return refused("AUTH_REQUIRED", "credential_rejected", status);
+    if (status === 403) return refused("LEGACY_AGENT_ACCESS_DENIED", "grant_or_membership_refused", status);
+    return refused("LEGACY_AGENT_ACCESS_UNAVAILABLE", "verification_failed", status);
+  }
+}

package/src/session/agent-registry.js

@@ -305,6 +305,7 @@ export async function registerAgent(
     role = "observer",
     targetPath = process.cwd(),
     trackProcessExit = true,
+    preserveIdentity = false,
   } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
@@ -320,7 +321,7 @@ export async function registerAgent(
   // a random hex blob. Caller-supplied real ids are NEVER renamed
   // (kill tests like PR 348/351 register `codex-task-holder-1` with
   // model="" and need the id to round-trip verbatim).
-  if (shouldAutoRenameInRegistry({ originalCallerAgentId })) {
+  if (!preserveIdentity && shouldAutoRenameInRegistry({ originalCallerAgentId })) {
     const existingAgents = await listAgentsInternal(paths);
     const friendly = assignFriendlyName({ model, existingAgents });
     if (friendly && friendly !== resolvedAgentId.toLowerCase()) {