agent-relay-server 0.83.0 → 0.84.0

package/src/routes/_shared.ts

@@ -5,7 +5,7 @@ import { ValidationError, createActivityEvent, createCallbackDelivery, finishCal
 import { cleanEpoch, cleanString, optionalEnum } from "../validation";
 import { emitActivityEvent, emitMessageQueued, emitNewMessage } from "../sse";
 import { emitRelayEvent } from "../events";
-import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isRecord, userSinkId } from "agent-relay-sdk";
+import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isHumanAgentId, isRecord, userIdFromAddress, userSinkId } from "agent-relay-sdk";
 import { authorizeAgentForUser, visibleAgentIdsForUser, type AgentAction } from "../agent-authz";
 import { generateSpawnRequestId } from "../spawn-command";
 import { getComponentAuth, getIntegrationAuth, isAuthorized, isRequestAuthorizedFor } from "../security";
@@ -58,13 +58,51 @@ export function authAuditMetadata(req: Request): Record<string, unknown> {
       },
     };
   }
-  return hasPresentedCredential(req) ? { auth: { type: "root" } } : {};
+  if (!hasPresentedCredential(req)) return {};
+  // Root (god-token) credential: stamp the seeded-admin identity it now carries (#389 break-glass),
+  // so the audit trail records *who* acted instead of an anonymous root.
+  const acting = resolveActingUser(req);
+  return acting
+    ? { auth: { type: "root", userId: acting.userId, source: acting.source } }
+    : { auth: { type: "root" } };
 }
 
 export function isRootCredentialRequest(req: Request): boolean {
   return hasPresentedCredential(req) && isAuthorized(req) && !getComponentAuth(req) && !getIntegrationAuth(req);
 }
 
+/**
+ * Which human is acting, and how their request was authenticated (#389). The single bridge from a
+ * request to a `users.id`:
+ * - a human session token (component token whose `sub` is a `user:<id>` address) → that user, via
+ *   the SDK resolver (never a hand-rolled namespace) — `source: "session"`;
+ * - the raw god-token / root credential (`isRootCredentialRequest`) → the seeded admin
+ *   `DEFAULT_USER_ID` with `source: "break-glass"`. This is what gives the env token an *identity*
+ *   instead of the anonymous "server" it carried before, while it KEEPS bypassing scope checks
+ *   unchanged (the gate in src/index.ts is untouched). Works with zero `auth_identities` rows, so
+ *   it is simultaneously the break-glass path and the first-user bootstrap.
+ *
+ * Returns null for a machine component/integration token (no human is acting).
+ */
+export type ActingUserSource = "session" | "break-glass";
+
+export interface ActingUser {
+  userId: string;
+  source: ActingUserSource;
+}
+
+export function resolveActingUser(req: Request): ActingUser | null {
+  const component = getComponentAuth(req);
+  if (component && isHumanAgentId(component.sub)) {
+    const userId = userIdFromAddress(component.sub);
+    if (userId) return { userId, source: "session" };
+  }
+  if (isRootCredentialRequest(req)) {
+    return { userId: DEFAULT_USER_ID, source: "break-glass" };
+  }
+  return null;
+}
+
 function sanitizeAttribution(raw: unknown): string | undefined {
   if (typeof raw !== "string") return undefined;
   // eslint-disable-next-line no-control-regex

package/src/routes/auth.ts

@@ -0,0 +1,107 @@
+// Authentication & session routes (#389). These four paths sit on a pre-auth PUBLIC ALLOWLIST
+// (src/index.ts) so they are reachable unauthenticated — each handler owns its own auth: login
+// verifies credentials, refresh validates the refresh token, logout revokes the presented session.
+// Everything else on the relay still flows through the existing component-token gate.
+import { isRecord, type User } from "agent-relay-sdk";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getAuthProvider, listAuthProviders, mintUserSession, resolveRefreshToken } from "../auth";
+import { getAuthIdentity, getUser } from "../db";
+import { revokeToken } from "../token-db.ts";
+import { getComponentAuth } from "../security";
+
+/** Public projection of a user for login/refresh responses — never leaks internal-only columns. */
+function userView(user: User): Record<string, unknown> {
+  return {
+    id: user.id,
+    handle: user.handle,
+    displayName: user.displayName,
+    role: user.role,
+    tenantId: user.tenantId,
+    avatarUrl: user.avatarUrl,
+  };
+}
+
+function sessionResponse(user: User): Response {
+  const session = mintUserSession(user);
+  return json({
+    tokenType: "Bearer",
+    accessToken: session.accessToken,
+    refreshToken: session.refreshToken,
+    expiresIn: session.expiresIn,
+    user: userView(user),
+  });
+}
+
+/** GET /api/auth/providers — the login screen reads this to render available login methods. */
+export const getAuthProvidersRoute: Handler = () =>
+  json({
+    providers: listAuthProviders().map((provider) => ({
+      id: provider.id,
+      displayName: provider.displayName,
+      flow: provider.flow,
+    })),
+  });
+
+/**
+ * POST /api/auth/login — body `{ provider, ...credentials }`. Resolves the provider, verifies the
+ * credentials to a `providerSubject`, maps it through `auth_identities` to a user, and mints a
+ * session. Every failure returns the same generic 401 (no provider/user/credential enumeration).
+ */
+export const postAuthLoginRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("login body required", 400);
+  const providerId = parsed.body.provider;
+  if (typeof providerId !== "string" || !providerId) return error("provider required", 400);
+
+  const provider = getAuthProvider(providerId);
+  if (!provider) return error("invalid credentials", 401);
+
+  const result = await provider.verify(parsed.body);
+  if (!result) return error("invalid credentials", 401);
+
+  const identity = getAuthIdentity(provider.id, result.providerSubject);
+  if (!identity) return error("invalid credentials", 401);
+
+  const user = getUser(identity.userId);
+  if (!user || user.status !== "active") return error("invalid credentials", 401);
+
+  return sessionResponse(user);
+};
+
+/**
+ * POST /api/auth/refresh — body `{ refreshToken }`. Validates the refresh token and mints a fresh
+ * session, rotating the refresh token: the consumed one is revoked so a captured refresh token is
+ * single-use. Returns the same generic 401 on any invalid/expired/revoked token.
+ */
+export const postAuthRefreshRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("refresh body required", 400);
+  const refreshToken = parsed.body.refreshToken;
+  if (typeof refreshToken !== "string" || !refreshToken) return error("refreshToken required", 400);
+
+  const resolved = resolveRefreshToken(refreshToken);
+  if (!resolved) return error("invalid refresh token", 401);
+
+  const response = sessionResponse(resolved.user);
+  // Rotate: revoke the consumed refresh token so it can't be replayed (the fresh pair supersedes it).
+  if (resolved.payload.jti) revokeToken(resolved.payload.jti, "rotation");
+  return response;
+};
+
+/**
+ * POST /api/auth/logout — revokes the presented session token and, if supplied, its refresh token.
+ * Idempotent: revoking an already-revoked or absent token is a no-op. Always returns 204.
+ */
+export const postAuthLogoutRoute: Handler = async (req) => {
+  const component = getComponentAuth(req);
+  if (component?.jti) revokeToken(component.jti, "admin");
+
+  const parsed = await parseBody<unknown>(req);
+  if (parsed.ok && isRecord(parsed.body) && typeof parsed.body.refreshToken === "string") {
+    const resolved = resolveRefreshToken(parsed.body.refreshToken);
+    if (resolved?.payload.jti) revokeToken(resolved.payload.jti, "admin");
+  }
+  return new Response(null, { status: 204 });
+};

package/src/routes/index.ts

@@ -18,6 +18,7 @@ import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute,
 import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
 import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceRecoveryBranches, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim, postWorkspaceRecoveryBranchDiscard } from "./workspaces";
 import { error, type Handler } from "./_shared";
+import { getAuthProvidersRoute, postAuthLoginRoute, postAuthLogoutRoute, postAuthRefreshRoute } from "./auth";
 import { getActivityEvents, postActivityEvent } from "./activity";
 import { getAnalyticsRoute, getHealthRoute, getMaintenanceJobs, getStatsRoute, postMaintenanceJobRun, postSystemReap } from "./stats";
 import { getApiDocs, getApiSpec } from "./spec";
@@ -69,6 +70,13 @@ function route(method: string, path: string, handler: Handler): Route {
 }
 
 const routes: Route[] = [
+  // Auth & sessions (#389). On the pre-auth public allowlist (src/index.ts) — each handler owns
+  // its own auth (login verifies credentials, refresh validates the refresh token, logout revokes).
+  route("GET", "/api/auth/providers", getAuthProvidersRoute),
+  route("POST", "/api/auth/login", postAuthLoginRoute),
+  route("POST", "/api/auth/refresh", postAuthRefreshRoute),
+  route("POST", "/api/auth/logout", postAuthLogoutRoute),
+
   route("POST", "/api/artifacts", postArtifact),
   route("GET", "/api/artifacts", getArtifacts),
   route("GET", "/api/artifacts/:id/content", getArtifactContent),

package/src/routes/tokens.ts

@@ -1,7 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: tokens.
-import { SPAWN_PROVIDERS, isRecord } from "agent-relay-sdk";
+import { SPAWN_PROVIDERS, isRecord, userSinkId } from "agent-relay-sdk";
 import { ValidationError, getOrchestrator, upsertIntegrationRegistry } from "../db";
-import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, type Handler } from "./_shared";
+import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, resolveActingUser, type Handler } from "./_shared";
 import { cleanString, cleanStringArray, cleanTokenConstraints, optionalEnum } from "../validation";
 import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenProfiles, listTokens, renewToken, revokeToken, updateTokenProfile, upsertTokenProfile } from "../token-db";
 import { getComponentAuth, getIntegrationAuth, isAuthorized } from "../security";
@@ -36,6 +36,12 @@ export const getTokenMe: Handler = (req) => {
   }
 
   if (isAuthorized(req)) {
+    // Root (god-token) now carries the seeded-admin identity (#389): report *who* is acting
+    // (break-glass → user:default) instead of the anonymous "server" it showed before.
+    const acting = resolveActingUser(req);
+    if (acting) {
+      return json({ actor: userSinkId(acting.userId), userId: acting.userId, source: acting.source, kind: "server", scopes: ["*"] });
+    }
     return json({ actor: "server", kind: "server", scopes: ["*"] });
   }
   return error("unauthorized", 401);

package/src/security.ts

@@ -539,7 +539,7 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   for (const [key, item] of Object.entries(record)) {
     if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
-    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId") {
+    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId" || key === "tenantId") {
       if (typeof item !== "string") return false;
     } else if (key === "maxSpawnedAgents") {
       if (typeof item !== "number") return false;

package/src/upgrade-install-verify.ts

@@ -0,0 +1,160 @@
+import { chmodSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Post-install verification + repair for a runtime-prefix upgrade (#631).
+ *
+ * A clean `npm install` exit code is NOT proof the upgrade landed: npm reports
+ * "up to date" (exit 0, nothing installed) when its hidden
+ * `node_modules/.package-lock.json` claims the target version while the extracted
+ * package dirs are still stale (lock-vs-disk divergence). That silently stranded
+ * macmini2 on 0.82.0 during the v0.83.0 deploy. This module asserts the ACTUAL
+ * on-disk versions, repairs the divergence by forcing a real re-extraction, and
+ * restores the exec bit that extraction drops from bin entries.
+ */
+
+/** Metadata describing what a runtime-prefix install action must verify. */
+export type VerifyInstall = {
+  /** Runtime prefix whose node_modules holds the installed packages. */
+  prefix: string;
+  targetVersion: string;
+  /** Package names (no version spec) to assert + repair + restore exec bits on. */
+  packages: string[];
+};
+
+type CommandOutput = { exitCode: number; stdout: string; stderr: string };
+
+/**
+ * Filesystem operations the verification needs, factored out so tests can drive
+ * the assertion/repair/exec-bit logic without a real npm install or touching
+ * disk. Defaults to {@link defaultInstallIo}.
+ */
+export type InstallIo = {
+  /** Actual installed version from `<prefix>/node_modules/<pkg>/package.json`. */
+  readInstalledVersion: (prefix: string, pkg: string) => string | undefined;
+  /** Delete `<prefix>/node_modules/<pkg>` so the next install must re-extract it. */
+  forceReextract: (prefix: string, pkg: string) => void;
+  /** Delete npm's hidden `<prefix>/node_modules/.package-lock.json`. */
+  removeHiddenLock: (prefix: string) => void;
+  /** chmod +x each of a package's bin entry targets; returns the files changed. */
+  restoreExecBits: (prefix: string, pkg: string) => string[];
+};
+
+type VersionMismatch = { pkg: string; expected: string; actual?: string };
+
+/**
+ * Assert the runtime packages reached the target version after npm reported
+ * success; on divergence, force a clean re-extraction and re-assert; finally
+ * restore the exec bit that npm extraction drops from bin entries. Appends a
+ * human-readable trace to `lines` and throws a loud, specific error on failure.
+ */
+export async function verifyAndRepairInstall(
+  action: { label: string; command: string[] },
+  verify: VerifyInstall,
+  runInstall: (command: string[]) => Promise<CommandOutput>,
+  io: InstallIo,
+  lines: string[],
+): Promise<void> {
+  const findMismatches = (): VersionMismatch[] =>
+    verify.packages
+      .map((pkg) => ({ pkg, expected: verify.targetVersion, actual: io.readInstalledVersion(verify.prefix, pkg) }))
+      .filter((m) => m.actual !== verify.targetVersion);
+
+  let mismatches = findMismatches();
+  if (mismatches.length > 0) {
+    // Lock-vs-disk divergence: npm's hidden node_modules/.package-lock.json
+    // claimed the target while the extracted dirs lagged, so `npm install`
+    // returned "up to date" and installed nothing. Drop the stale dirs + hidden
+    // lock so the reinstall is forced to actually re-extract the tarballs.
+    lines.push(
+      `Installed versions disagree with ${verify.targetVersion} after npm reported success ` +
+      `(lock-vs-disk divergence): ${formatMismatches(mismatches)}. Forcing a clean re-extraction.`,
+    );
+    for (const m of mismatches) io.forceReextract(verify.prefix, m.pkg);
+    io.removeHiddenLock(verify.prefix);
+
+    const result = await runInstall(action.command);
+    if (result.stdout.trim()) lines.push(result.stdout.trim());
+    if (result.stderr.trim()) lines.push(result.stderr.trim());
+    if (result.exitCode !== 0) {
+      const detail = (result.stderr.trim() || result.stdout.trim()).slice(-2000);
+      throw new Error(`${action.label} re-extraction failed with exit code ${result.exitCode}${detail ? `:\n${detail}` : ""}`);
+    }
+
+    mismatches = findMismatches();
+    if (mismatches.length > 0) {
+      throw new Error(
+        `${action.label} did not install ${verify.targetVersion}: ${formatMismatches(mismatches)}. ` +
+        `npm reported success but the runtime is unchanged; re-run the upgrade or inspect ${join(verify.prefix, "node_modules")}.`,
+      );
+    }
+    lines.push(`Re-extraction reconciled the runtime to ${verify.targetVersion}.`);
+  }
+
+  // npm extraction creates bin entry files mode 0644 (no +x). The systemd units
+  // ExecStart the .bin symlink → src/index.ts directly, which needs the exec bit
+  // or it dies with status=203/EXEC. Restore +x on every upgraded package's bin
+  // targets so a re-extracted runtime still starts.
+  const restored: string[] = [];
+  for (const pkg of verify.packages) restored.push(...io.restoreExecBits(verify.prefix, pkg));
+  if (restored.length > 0) {
+    lines.push(`Restored exec bit on ${restored.length} runtime bin entr${restored.length === 1 ? "y" : "ies"}.`);
+  }
+}
+
+function formatMismatches(mismatches: VersionMismatch[]): string {
+  return mismatches.map((m) => `${m.pkg} (expected ${m.expected}, got ${m.actual ?? "not installed"})`).join(", ");
+}
+
+/** Strip the version spec from a package install arg (`name@1.2.3` → `name`). */
+export function packageName(spec: string): string {
+  const at = spec.lastIndexOf("@");
+  return at > 0 ? spec.slice(0, at) : spec;
+}
+
+export const defaultInstallIo: InstallIo = {
+  readInstalledVersion(prefix, pkg) {
+    const manifest = join(prefix, "node_modules", pkg, "package.json");
+    if (!existsSync(manifest)) return undefined;
+    try {
+      return (JSON.parse(readFileSync(manifest, "utf8")) as { version?: string }).version;
+    } catch {
+      return undefined;
+    }
+  },
+  forceReextract(prefix, pkg) {
+    rmSync(join(prefix, "node_modules", pkg), { recursive: true, force: true });
+  },
+  removeHiddenLock(prefix) {
+    rmSync(join(prefix, "node_modules", ".package-lock.json"), { force: true });
+  },
+  restoreExecBits(prefix, pkg) {
+    const pkgDir = join(prefix, "node_modules", pkg);
+    const manifest = join(pkgDir, "package.json");
+    if (!existsSync(manifest)) return [];
+    let bin: unknown;
+    try {
+      bin = (JSON.parse(readFileSync(manifest, "utf8")) as { bin?: unknown }).bin;
+    } catch {
+      return [];
+    }
+    const targets = typeof bin === "string"
+      ? [bin]
+      : bin && typeof bin === "object"
+        ? Object.values(bin as Record<string, unknown>).filter((v): v is string => typeof v === "string")
+        : [];
+    const restored: string[] = [];
+    for (const rel of targets) {
+      const file = join(pkgDir, rel);
+      if (!existsSync(file)) continue;
+      try {
+        chmodSync(file, 0o755);
+        restored.push(file);
+      } catch {
+        // Best-effort: a chmod failure is surfaced later by the service refusing
+        // to start; don't abort the whole upgrade on a single unreadable bin.
+      }
+    }
+    return restored;
+  },
+};

package/src/upgrade.ts

@@ -5,6 +5,7 @@ import { VERSION, cliRelayUrl, relayAuthHeaders } from "./config";
 import type { RuntimeContracts, RuntimePackageMetadata } from "./contracts";
 import { defaultRuntimePrefix, runtimeBinPath } from "./runtime-prefix";
 import { resolveLocalOrchestratorId } from "./upgrade-local-id";
+import { defaultInstallIo, packageName, verifyAndRepairInstall, type InstallIo, type VerifyInstall } from "./upgrade-install-verify";
 import { errMessage, runInstallWithRetry } from "agent-relay-sdk";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 
@@ -72,6 +73,12 @@ type UpgradeAction = {
   reason: string;
   mutates: boolean;
   retryInstall?: boolean;
+  /**
+   * Post-install verification metadata for a runtime-prefix install (#631).
+   * When set, the executor asserts each package's ACTUAL on-disk version equals
+   * the target, repairs lock-vs-disk divergence, and restores bin exec bits.
+   */
+  verifyInstall?: VerifyInstall;
 };
 
 type UpgradePlan = {
@@ -183,6 +190,12 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
       reason: `Update server${runnerRequested ? ", provider runner" : ""}${orchestratorRequested ? ", and orchestrator" : ""} packages to ${targetVersion}.`,
       mutates: true,
       retryInstall: true,
+      // Only the isolated runtime prefix has a deterministic node_modules path we
+      // can read actual versions from (and it's the systemd-managed deploy that
+      // strands hosts on a silent no-op). Global bun/npm installs are left as-is.
+      verifyInstall: snapshot.packageManager === "runtime-npm"
+        ? { prefix: snapshot.runtimePrefix, targetVersion, packages: packages.map(packageName) }
+        : undefined,
     });
     if (snapshot.packageManager === "runtime-npm") {
       actions.push({
@@ -268,6 +281,8 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
 type ExecuteUpgradeOptions = {
   dryRun?: boolean;
   runner?: Runner;
+  /** Filesystem ops for post-install verification (injectable for tests). */
+  installIo?: InstallIo;
   /** Re-register grace window for post-restart version checks (default 30s). */
   verifyTimeoutMs?: number;
   /** Poll interval while waiting for re-register (default 1s). */
@@ -283,6 +298,7 @@ type ExecuteUpgradeOptions = {
 export async function executeUpgradePlan(plan: UpgradePlan, options: ExecuteUpgradeOptions = {}): Promise<string> {
   if (options.dryRun) return formatUpgradePlan(plan, { dryRun: true });
   const runner = options.runner ?? runCommand;
+  const io = options.installIo ?? defaultInstallIo;
   const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
   const probeServerVersion = options.probeServerVersion ?? runningServerVersion;
   const probeOrchestrators = options.probeOrchestrators ?? runningOrchestrators;
@@ -301,23 +317,36 @@ export async function executeUpgradePlan(plan: UpgradePlan, options: ExecuteUpgr
     return value;
   };
   const lines = [`Upgrading Agent Relay to ${plan.targetVersion}`];
+  const runInstall = (command: string[]) => runInstallWithRetry(command, runner, {
+    sleep,
+    retries: options.installRetries,
+    baseDelayMs: options.installRetryBaseMs,
+    onRetry: ({ attempt, delayMs }) => {
+      lines.push(`npm cache race detected; retrying install attempt ${attempt} in ${delayMs}ms.`);
+    },
+  });
   for (const action of plan.actions) {
     lines.push(`\n${action.label}`);
     lines.push(`$ ${action.command.map(shellQuote).join(" ")}`);
-    const result = action.retryInstall
-      ? await runInstallWithRetry(action.command, runner, {
-        sleep,
-        retries: options.installRetries,
-        baseDelayMs: options.installRetryBaseMs,
-        onRetry: ({ attempt, delayMs }) => {
-          lines.push(`npm cache race detected; retrying install attempt ${attempt} in ${delayMs}ms.`);
-        },
-      })
-      : runner(action.command);
+    const result = action.retryInstall ? await runInstall(action.command) : runner(action.command);
     if (result.stdout.trim()) lines.push(result.stdout.trim());
     if (result.stderr.trim()) lines.push(result.stderr.trim());
     if (result.exitCode !== 0) {
-      throw new Error(`${action.label} failed with exit code ${result.exitCode}`);
+      // Surface the child command's own output in the thrown error, not just the
+      // exit code (#631). The CLI reports only the error message on failure, so a
+      // bare "failed with exit code 1" hides the npm resolver failure and forces
+      // guess-and-check. The orchestrator self-upgrade path (self-upgrade.ts)
+      // already attaches the captured output — mirror it here so the local path
+      // is just as diagnosable.
+      const detail = (result.stderr.trim() || result.stdout.trim()).slice(-2000);
+      throw new Error(`${action.label} failed with exit code ${result.exitCode}${detail ? `:\n${detail}` : ""}`);
+    }
+    // A clean exit code is NOT proof the upgrade landed: npm reports "up to date"
+    // (exit 0, nothing installed) when its hidden lock claims the target while the
+    // extracted dirs are stale. Assert actual on-disk versions, repair divergence,
+    // and restore exec bits dropped by re-extraction (#631).
+    if (action.verifyInstall) {
+      await verifyAndRepairInstall(action, action.verifyInstall, runInstall, io, lines);
     }
   }
   if (plan.actions.some((action) => action.command.join(" ") === "systemctl --user restart agent-relay.service")) {

package/src/validation.ts

@@ -124,6 +124,8 @@ export function cleanTokenConstraints(value: unknown): TokenConstraints | undefi
   if (cwd) constraints.cwd = cwd;
   const teamId = cleanString(value.teamId, "constraints.teamId", { max: 120 });
   if (teamId) constraints.teamId = teamId;
+  const tenantId = cleanString(value.tenantId, "constraints.tenantId", { max: 120 });
+  if (tenantId) constraints.tenantId = tenantId;
   for (const key of ["terminalAttach", "logsRead", "canDelegate"] as const) {
     if (value[key] !== undefined) {
       if (typeof value[key] !== "boolean") throw new ValidationError(`constraints.${key} must be a boolean`);