@myspec/mcp-server 1.1.1-next.156 → 1.1.1-next.158

package/README.md

@@ -19,13 +19,19 @@ Run with `npx @myspec/mcp-server [command]` (or `myspec-mcp [command]` when inst
 ```text
 (default)                 Start MCP server over stdio
 serve                     Start MCP server over stdio
-login                     Sign in via browser loopback OAuth
-login --paste             Same as login, but never auto-opens a browser
-login --org <slug>        Sign in and pin that organization
-logout                    Revoke refresh token and clear local credentials
+auth login                Sign in via browser loopback OAuth
+auth login --paste        Same as auth login, but never auto-opens a browser
+auth login --org <slug>   Sign in and pin that organization
+auth logout               Revoke refresh token and clear local credentials
+auth status               Show the sign-in: account email and active organization
+login, logout             Aliases for `auth login` and `auth logout`
 reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
+`login` and `logout` keep working exactly as before; they run `auth login` and
+`auth logout`. Add `--help` after any auth command to print the usage instead
+of running it.
+
 ### Signing in from another device (`--paste`)
 
 `login` opens a browser on this machine and catches the callback on a local
@@ -239,6 +245,45 @@ dev environment:
 npx -y @myspec/mcp-server login --user-auth-url https://dev-auth.myspec.dev
 ```
 
+### Checking your sign-in (`auth status`)
+
+```bash
+npx -y @myspec/mcp-server auth status
+```
+
+```text
+Signed in to https://auth.myspec.dev
+  Account:       jane@example.com
+  Organization:  Acme Inc (acme)
+  Credential:    login session (/home/jane/.myspec/oauth_creds.json)
+```
+
+It reports the credential `serve` would use, in the same precedence order
+(`MYSPEC_API_TOKEN` > file `apiToken` > the `login` session), and honours
+`--user-auth-url` the same way. The first line names the auth server, which is
+how you tell a dev sign-in from a production one.
+
+- **What is checked online.** The email and organization come from the saved
+  access token while it is still valid (they last 15 minutes); once it has
+  expired, `auth status` renews it first, like any other command. For a login
+  session it then looks the organization name up from user-auth, which also
+  confirms the session: one that was ended on the server is reported as signed
+  out. `MYSPEC_API_TOKEN` is exchanged on every run. A file `apiToken` whose
+  saved access token is still valid is not checked with the server, so a token
+  revoked in the webapp can still show as signed in for up to 15 minutes.
+- **API tokens show the organization slug only**, e.g.
+  `acme (API tokens do not include the organization name)`, plus the token's
+  access mode (`read-only` or `read-write`). user-auth has no endpoint that
+  returns the name for an API token.
+- **No active organization** prints `Organization: none` and how to pin one.
+- **If the name lookup fails** (the network, or a server error), the slug is
+  shown with the reason and the command still succeeds.
+- **Exit codes:** `0` when signed in; `2` when not signed in, when the
+  credential is rejected, or when an expired token could not be renewed — so
+  `auth status || auth login` works in a script. A problem with the
+  credentials file itself (wrong file mode, bad JSON) fails the same way
+  `serve` does. A failure never deletes the saved credentials.
+
 ### `reverse`
 
 `reverse` connects out to the ai-agent service over WebSocket and exposes a set

package/dist/index.js

@@ -316,7 +316,88 @@ function createFileCredentialsStore(paths = {}) {
     },
     async clear() {
       await unlinkIfExists(oauthCredsPath);
+    },
+    withLock: (fn) => withFileLock(`${oauthCredsPath}.lock`, fn, paths.lockTimings),
+    saveSettings: (creds) => writeSettingsFile(settingsPath, creds)
+  };
+}
+function saveDiscoveredUrls(store, creds) {
+  return store.saveSettings ? store.saveSettings(creds) : store.save(creds);
+}
+var DEFAULT_LOCK_TIMINGS = { staleMs: 3e4, waitMs: 2e4, pollMs: 50 };
+async function withFileLock(lockPath, fn, timings = DEFAULT_LOCK_TIMINGS) {
+  const owner = await acquireFileLock(lockPath, timings);
+  try {
+    return await fn();
+  } finally {
+    if (owner !== null) {
+      await releaseFileLock(lockPath, owner);
+    }
+  }
+}
+async function acquireFileLock(lockPath, timings) {
+  const owner = randomUUID();
+  const deadline = Date.now() + timings.waitMs;
+  try {
+    await fs.mkdir(path.dirname(lockPath), { recursive: true, mode: 448 });
+  } catch {
+    return null;
+  }
+  for (; ; ) {
+    try {
+      await fs.writeFile(lockPath, owner, { flag: "wx", mode: 384 });
+      return owner;
+    } catch (err) {
+      if (!isFsExists(err)) {
+        return null;
+      }
+    }
+    if (Date.now() >= deadline) {
+      return null;
+    }
+    const held = await readLock(lockPath);
+    if (held === null) {
+      continue;
+    }
+    if (held.ageMs > timings.staleMs) {
+      const again = await readLock(lockPath);
+      if (again?.owner !== held.owner) {
+        continue;
+      }
+      try {
+        await fs.unlink(lockPath);
+      } catch (err) {
+        if (!isFsNotFound(err)) {
+          return null;
+        }
+      }
+      continue;
     }
+    await new Promise((resolve3) => setTimeout(resolve3, timings.pollMs));
+  }
+}
+async function readLock(lockPath) {
+  try {
+    const [stat2, owner] = await Promise.all([fs.stat(lockPath), fs.readFile(lockPath, "utf-8")]);
+    return { owner, ageMs: Date.now() - stat2.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+async function releaseFileLock(lockPath, owner) {
+  const current = await fs.readFile(lockPath, "utf-8").catch(() => null);
+  if (current === owner) {
+    await unlinkIfExists(lockPath).catch(() => void 0);
+  }
+}
+function keepCredentialsOnFailure(store) {
+  return {
+    load: () => store.load(),
+    save: (creds) => store.save(creds),
+    clear: () => Promise.resolve(),
+    path: () => store.path(),
+    ...store.withLock ? { withLock: store.withLock } : {},
+    ...store.saveSettings ? { saveSettings: store.saveSettings } : {}
   };
 }
 async function writeSettingsFile(target, creds) {
@@ -588,15 +669,30 @@ function requireNumber(obj, key) {
 function isFsNotFound(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
+function isFsExists(err) {
+  return typeof err === "object" && err !== null && err.code === "EEXIST";
+}
 
 // src/auth/token-manager.ts
 var EXPIRY_SKEW_MS = 3e4;
+var REFRESH_TIMEOUT_MS = 8e3;
 var TokenManager = class {
   store;
   fetchImpl;
   now;
   cached = null;
   refreshInFlight = null;
+  /**
+   * Whether the refresh in flight is guaranteed to mint. An unforced one may
+   * settle for a token another process saved, which a forced caller must not
+   * be handed — see refresh().
+   */
+  refreshInFlightForced = false;
+  /**
+   * The access token this instance last minted, so a forced caller that
+   * waited on an unforced refresh can tell whether it got a minted token.
+   */
+  lastMintedAccessToken = null;
   /**
    * The in-flight disk read, shared by every concurrent caller.
    *
@@ -644,18 +740,25 @@ var TokenManager = class {
   }
   async getValidAccessToken() {
     const creds = await this.ensureLoaded();
-    if (creds.expiresAt > this.now() + EXPIRY_SKEW_MS) {
+    if (this.isFresh(creds)) {
       return creds.accessToken;
     }
-    const refreshed = await this.refresh(creds);
+    const refreshed = await this.refresh(creds, { forced: false });
     return refreshed.accessToken;
   }
   async getCredentials() {
     return this.ensureLoaded();
   }
+  /**
+   * Mints a new access token even if the current one has not expired — for
+   * callers whose token was just refused, or that need claims stamped after a
+   * server-side change (login re-minting after an organization switch). So,
+   * unlike getValidAccessToken, it never settles for a token another process
+   * already saved.
+   */
   async forceRefresh() {
     const creds = await this.ensureLoaded();
-    const refreshed = await this.refresh(creds);
+    const refreshed = await this.refresh(creds, { forced: true });
     return refreshed.accessToken;
   }
   async clear() {
@@ -681,16 +784,27 @@ var TokenManager = class {
     }
     return loaded;
   }
-  async refresh(creds) {
+  isFresh(creds) {
+    return creds.expiresAt > this.now() + EXPIRY_SKEW_MS;
+  }
+  async refresh(creds, opts) {
     if (this.refreshInFlight) {
-      return this.refreshInFlight;
+      if (this.refreshInFlightForced || !opts.forced) {
+        return this.refreshInFlight;
+      }
+      const settled = await this.refreshInFlight;
+      if (settled.accessToken === this.lastMintedAccessToken) {
+        return settled;
+      }
+      return this.refresh(this.cached ?? creds, opts);
     }
-    this.refreshInFlight = this.doRefresh(creds).finally(() => {
+    this.refreshInFlightForced = opts.forced;
+    this.refreshInFlight = this.doRefresh(creds, opts).finally(() => {
       this.refreshInFlight = null;
     });
     return this.refreshInFlight;
   }
-  async doRefresh(creds) {
+  async doRefresh(creds, opts) {
     if (creds.apiToken) {
       if (this.apiTokenRejection) {
         throw this.apiTokenRejection;
@@ -702,18 +816,100 @@ var TokenManager = class {
         "No credential is configured. Either set MYSPEC_API_TOKEN to a long-lived API token (or put one in the `apiToken` field of your credentials file) \u2014 create one in the MySpec webapp under the avatar menu, API tokens \u2014 or run `npx @myspec/mcp-server login` to sign in interactively."
       );
     }
+    return this.refreshSession(creds, opts);
+  }
+  /**
+   * Refreshes a login session that other processes may be refreshing too.
+   *
+   * Refresh tokens are single-use, and user-auth honours the previous one for
+   * only 60 seconds after a rotation. Every MCP client spawns its own `serve`,
+   * and `reverse` and `auth status` run beside them, all on the same
+   * ~/.myspec. This instance caches the credentials once, so when another
+   * process rotated the token, the cached one is already retired: presenting
+   * it gets a 401, and treating that as "signed out" used to delete the file —
+   * along with the valid token the other process had just saved.
+   *
+   * So the whole read → refresh → save runs under the store's lock, and the
+   * store is re-read first: a session rotated elsewhere is adopted (see
+   * newerSession), used as it is while its access token is fresh, otherwise
+   * refreshed with its token. While every process refreshing this file holds
+   * the lock, none can rotate in between. The lock is best-effort, though — a
+   * store without one, a lock not acquired in time or taken over as stale, an
+   * older CLI version — so a refusal is checked the same way, since a rotation
+   * can land while our request is in flight, and gets one retry with the newer
+   * token. Only then is the store cleared — and only if it still holds a token
+   * that was refused (see clearUnlessReplaced).
+   */
+  refreshSession(cachedCreds, opts) {
+    const run = () => this.refreshSessionLocked(cachedCreds, opts);
+    return this.store.withLock ? this.store.withLock(run) : run();
+  }
+  async refreshSessionLocked(cachedCreds, opts) {
+    const refused = /* @__PURE__ */ new Set();
+    let creds = cachedCreds;
+    let onDisk = await this.readStore();
+    const newer = newerSession(onDisk, creds);
+    if (newer) {
+      this.cached = newer;
+      if (!opts.forced && this.isFresh(newer)) {
+        return newer;
+      }
+      creds = newer;
+    }
     try {
-      return await this.performRefresh(creds);
+      return await this.performRefresh(creds, onDisk?.apiToken);
     } catch (err) {
-      await this.invalidateOnAuthFailure(err);
-      throw err;
+      if (!(err instanceof NeedsLoginError)) {
+        throw err;
+      }
+      refused.add(creds.refreshToken ?? "");
+      onDisk = await this.readStore();
+      const raced = newerSession(onDisk, creds);
+      if (!raced) {
+        await this.clearUnlessReplaced(onDisk, refused);
+        throw err;
+      }
+      this.cached = raced;
+      if (!opts.forced && this.isFresh(raced)) {
+        return raced;
+      }
+      try {
+        return await this.performRefresh(raced, onDisk?.apiToken);
+      } catch (retryErr) {
+        if (retryErr instanceof NeedsLoginError) {
+          refused.add(raced.refreshToken ?? "");
+          await this.clearUnlessReplaced(await this.readStore(), refused);
+        }
+        throw retryErr;
+      }
     }
   }
-  async invalidateOnAuthFailure(err) {
-    if (err instanceof NeedsLoginError) {
-      this.cached = null;
-      await this.store.clear();
+  /**
+   * A fresh read of the store; null when it is empty or cannot be read, so a
+   * refresh that would work is not failed by it.
+   */
+  readStore() {
+    return this.store.load().catch(() => null);
+  }
+  /**
+   * Signs out after a refusal: drops the cache and clears the store — unless
+   * the store no longer holds a refused token. An API-token record is shown
+   * exactly once and is never ours to delete, and a session we have not
+   * presented belongs to another process. A store that could not be read is
+   * left alone too: it may hold either (a hand edit with a typo, a bad file
+   * mode), and its own error is what the user needs to see. Network errors,
+   * 5xx and other transient faults never reach here: they must not delete the
+   * stored refresh token.
+   */
+  async clearUnlessReplaced(onDisk, refused) {
+    this.cached = null;
+    if (!onDisk || onDisk.apiToken !== void 0) {
+      return;
+    }
+    if (onDisk.refreshToken !== void 0 && !refused.has(onDisk.refreshToken)) {
+      return;
     }
+    await this.store.clear();
   }
   /**
    * Trades the long-lived API token for a short-lived access token.
@@ -766,15 +962,26 @@ var TokenManager = class {
       expiresAt: this.now() + payload.expiresIn * 1e3
     };
     this.cached = next;
-    await this.store.save(next);
+    this.lastMintedAccessToken = next.accessToken;
+    const onDisk = await this.readStore();
+    if (onDisk?.apiToken === apiToken) {
+      await this.store.save({ ...onDisk, accessToken: next.accessToken, expiresAt: next.expiresAt });
+    }
     return next;
   }
-  async performRefresh(creds) {
+  /**
+   * @param keepApiToken An API token the store holds beside this session —
+   *   added by hand while this process ran. Written back with the rotated pair,
+   *   since save() rewrites the whole file and a PAT is shown exactly once; the
+   *   cache stays on the session, so this process does not switch identity.
+   */
+  async performRefresh(creds, keepApiToken) {
     const url = `${creds.userAuthUrl}/api/auth/token/refresh`;
     const response = await this.fetchImpl(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refreshToken: creds.refreshToken })
+      body: JSON.stringify({ refreshToken: creds.refreshToken }),
+      signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS)
     });
     if (response.status === 400 || response.status === 401 || response.status === 403 || response.status === 422) {
       throw new RefreshRejectedError(
@@ -785,7 +992,8 @@ var TokenManager = class {
       const body = await response.text().catch(() => "");
       throw new HttpStatusError(response.status, body, `Token refresh failed: HTTP ${String(response.status)}`);
     }
-    const payload = await response.json().catch(() => null);
+    const text = await response.text();
+    const payload = parseJson(text);
     if (!payload || typeof payload.accessToken !== "string" || typeof payload.refreshToken !== "string" || typeof payload.expiresIn !== "number") {
       throw new NeedsLoginError(
         "Token refresh response was malformed. Run `npx @myspec/mcp-server login` to sign in again."
@@ -798,10 +1006,24 @@ var TokenManager = class {
       expiresAt: this.now() + payload.expiresIn * 1e3
     };
     this.cached = next;
-    await this.store.save(next);
+    this.lastMintedAccessToken = next.accessToken;
+    await this.store.save(keepApiToken === void 0 ? next : { ...next, apiToken: keepApiToken });
     return next;
   }
 };
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function newerSession(onDisk, creds) {
+  if (onDisk?.refreshToken === void 0 || onDisk.refreshToken === creds.refreshToken || onDisk.userAuthUrl !== creds.userAuthUrl || onDisk.expiresAt <= creds.expiresAt) {
+    return null;
+  }
+  return { ...onDisk, apiToken: void 0 };
+}
 var RefreshRejectedError = class extends NeedsLoginError {
 };
 var ApiTokenRejectedError = class extends ConfigError {
@@ -809,19 +1031,36 @@ var ApiTokenRejectedError = class extends ConfigError {
 
 // src/auth/organization.ts
 import readline2 from "readline";
-function readOrgClaim(accessToken) {
+
+// src/auth/token-claims.ts
+function readTokenClaims(accessToken) {
   const payload = accessToken.split(".")[1];
   if (payload === void 0) {
-    return void 0;
+    return {};
   }
+  let claims;
   try {
-    const json = Buffer.from(payload, "base64url").toString("utf-8");
-    const claims = JSON.parse(json);
-    const org = claims.org;
-    return typeof org === "string" && org.length > 0 ? org : void 0;
+    claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
   } catch {
-    return void 0;
+    return {};
   }
+  if (typeof claims !== "object" || claims === null) {
+    return {};
+  }
+  const record = claims;
+  return {
+    email: nonEmptyString(record.email),
+    org: nonEmptyString(record.org),
+    access: nonEmptyString(record.access)
+  };
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/auth/organization.ts
+function readOrgClaim(accessToken) {
+  return readTokenClaims(accessToken).org;
 }
 var NO_ACTIVE_ORG_HINT = "Your CLI session has no active organization, so the access token is missing the `org` claim that the platform API and ai-agent require. Run `npx @myspec/mcp-server login --org <slug>` to pin one.";
 async function listOrganizations(opts) {
@@ -1111,9 +1350,13 @@ async function runLogin(options, deps = {}) {
     webappUrl: config.webappUrl
   });
   const enriched = await discoverAfterLogin(credentials, config.webappUrl, deps.discover, log);
-  const prior = await store.load().catch(() => null);
-  const preserved = prior?.apiToken === void 0 ? enriched : { ...enriched, apiToken: prior.apiToken };
-  await store.save(preserved);
+  const persist = async () => {
+    const prior = await store.load().catch(() => null);
+    const merged = prior?.apiToken === void 0 ? enriched : { ...enriched, apiToken: prior.apiToken };
+    await store.save(merged);
+    return merged;
+  };
+  const preserved = await (store.withLock ? store.withLock(persist) : persist());
   log(`Signed in as ${enriched.user?.email ?? "unknown"}.`);
   log(`Credentials saved to ${store.path()}`);
   await ensureActiveOrganization({
@@ -1196,15 +1439,23 @@ async function ensureActiveOrganization(args) {
   log(`Active organization: ${mintedOrg}`);
 }
 function defaultRefreshTokens(store) {
-  const tokenManager = new TokenManager({ store: keepCredentialsOnFailure(store) });
+  const tokenManager = new TokenManager({ store: sessionOnly(store) });
   return tokenManager.forceRefresh();
 }
-function keepCredentialsOnFailure(store) {
+function sessionOnly(store) {
   return {
-    load: () => store.load(),
-    save: (creds) => store.save(creds),
+    load: async () => {
+      const creds = await store.load();
+      return creds === null ? null : { ...creds, apiToken: void 0 };
+    },
+    save: async (creds) => {
+      const current = await store.load();
+      const apiToken = creds.apiToken ?? current?.apiToken;
+      await store.save(apiToken === void 0 ? creds : { ...creds, apiToken });
+    },
     clear: () => Promise.resolve(),
-    path: () => store.path()
+    path: () => store.path(),
+    ...store.withLock ? { withLock: store.withLock } : {}
   };
 }
 function sameSlug(a, b) {
@@ -1289,6 +1540,153 @@ async function runLogout(env = process.env) {
   }
 }
 
+// src/cli/auth-status.ts
+var NOT_SIGNED_IN = "Not signed in. Run `npx @myspec/mcp-server auth login` to sign in, or set MYSPEC_API_TOKEN to a MySpec API token.";
+var SESSION_REVOKED = "Your saved sign-in is no longer valid: the session was ended on the server. Run `npx @myspec/mcp-server auth login` to sign in again.";
+async function resolveAuthStatus(deps) {
+  const stored = await deps.store.load();
+  if (!stored) {
+    throw new NeedsLoginError(NOT_SIGNED_IN);
+  }
+  let accessToken;
+  try {
+    accessToken = await deps.getAccessToken();
+  } catch (err) {
+    throw describeTokenFailure(err, stored.userAuthUrl);
+  }
+  const claims = readTokenClaims(accessToken);
+  const kind = credentialKind(stored, deps.envApiTokenActive);
+  const status = {
+    userAuthUrl: stored.userAuthUrl,
+    credential: { kind, location: deps.store.path() },
+    // The saved user is the fallback only: an API-token record has none.
+    email: claims.email ?? stored.user?.email,
+    access: claims.access
+  };
+  const slug = claims.org;
+  if (slug === void 0) {
+    return status;
+  }
+  if (kind !== "login-session") {
+    return {
+      ...status,
+      organization: { slug },
+      orgNameNote: "API tokens do not include the organization name"
+    };
+  }
+  let organizations;
+  try {
+    organizations = await deps.listOrgs({
+      userAuthUrl: stored.userAuthUrl,
+      accessToken,
+      webappUrl: stored.webappUrl ?? deps.webappUrl
+    });
+  } catch (err) {
+    if (err instanceof HttpStatusError && err.status === 401) {
+      throw new NeedsLoginError(SESSION_REVOKED);
+    }
+    return {
+      ...status,
+      organization: { slug },
+      orgNameNote: `could not look up its name: ${errorMessage2(err)}`
+    };
+  }
+  const match = organizations.find((org) => org.slug.toLowerCase() === slug.toLowerCase());
+  if (!match) {
+    return {
+      ...status,
+      organization: { slug },
+      orgNameNote: "not among your organizations; it may have been deleted, or you were removed"
+    };
+  }
+  return { ...status, organization: { slug, name: match.name } };
+}
+function describeTokenFailure(err, userAuthUrl) {
+  if (err instanceof TypeError || err instanceof Error && err.name === "TimeoutError") {
+    return new ConfigError(
+      `Could not reach ${userAuthUrl} to check the sign-in: ${errorMessage2(err)}`
+    );
+  }
+  if (err instanceof HttpStatusError) {
+    return new ConfigError(
+      `Could not check the sign-in against ${userAuthUrl}: ${errorMessage2(err)}`
+    );
+  }
+  return err;
+}
+function credentialKind(stored, envApiTokenActive) {
+  if (stored.apiToken === void 0) {
+    return "login-session";
+  }
+  return envApiTokenActive ? "env-api-token" : "file-api-token";
+}
+function formatAuthStatus(status) {
+  const lines = [
+    `Signed in to ${status.userAuthUrl}`,
+    `  Account:       ${status.email ?? "unknown"}`,
+    `  Organization:  ${formatOrganization(status)}`,
+    `  Credential:    ${formatCredential(status)}`
+  ];
+  if (status.organization === void 0) {
+    lines.push("", `Warning: ${NO_ACTIVE_ORG_HINT}`);
+  }
+  return lines;
+}
+function formatOrganization(status) {
+  const org = status.organization;
+  if (org === void 0) {
+    return "none";
+  }
+  if (org.name !== void 0) {
+    return `${org.name} (${org.slug})`;
+  }
+  return status.orgNameNote === void 0 ? org.slug : `${org.slug} (${status.orgNameNote})`;
+}
+function formatCredential(status) {
+  const access = status.access === void 0 ? "" : ` (${formatAccess(status.access)})`;
+  switch (status.credential.kind) {
+    case "env-api-token":
+      return `API token from MYSPEC_API_TOKEN${access}`;
+    case "file-api-token":
+      return `API token in ${status.credential.location}${access}`;
+    case "login-session":
+      return `login session (${status.credential.location})`;
+  }
+}
+function formatAccess(access) {
+  if (access === "read") {
+    return "read-only";
+  }
+  if (access === "write") {
+    return "read-write";
+  }
+  return access;
+}
+function errorMessage2(err) {
+  return redactSensitive(err instanceof Error ? err.message : String(err));
+}
+async function runAuthStatus(options, deps = {}) {
+  const log = deps.log ?? ((message) => {
+    process.stderr.write(message + "\n");
+  });
+  const tokenManager = new TokenManager({
+    store: keepCredentialsOnFailure(options.store),
+    fetchImpl: deps.fetchImpl
+  });
+  const listOrgs = deps.listOrgs ?? ((opts) => listOrganizations({ ...opts, fetchImpl: deps.fetchImpl }));
+  const status = await resolveAuthStatus({
+    store: options.store,
+    getAccessToken: () => tokenManager.getValidAccessToken(),
+    listOrgs,
+    webappUrl: options.webappUrl,
+    envApiTokenActive: options.envApiTokenActive
+  });
+  for (const line of formatAuthStatus(status)) {
+    log(line);
+  }
+  return status;
+}
+
 // src/platform/client.ts
 import { createHash } from "crypto";
 
@@ -7328,7 +7726,7 @@ async function handleList(args, opts) {
   try {
     await walk(realPath, "");
   } catch (err) {
-    return structuredError("list_dir_failed", errorMessage2(err));
+    return structuredError("list_dir_failed", errorMessage3(err));
   }
   return structuredOk({ entries, truncated });
 }
@@ -7349,7 +7747,7 @@ async function handleRead(args, opts) {
   try {
     stat2 = await fs4.stat(realPath);
   } catch (err) {
-    return structuredError("stat_failed", errorMessage2(err));
+    return structuredError("stat_failed", errorMessage3(err));
   }
   if (!stat2.isFile()) {
     return structuredError("not_a_file", `Not a regular file: ${args.path}`);
@@ -7365,7 +7763,7 @@ async function handleRead(args, opts) {
   try {
     raw = await fs4.readFile(realPath);
   } catch (err) {
-    return structuredError("read_failed", errorMessage2(err));
+    return structuredError("read_failed", errorMessage3(err));
   }
   const probe = raw.subarray(0, Math.min(READ_FILE_BINARY_PROBE_BYTES, raw.length));
   if (probe.includes(0)) {
@@ -7572,7 +7970,7 @@ async function nodeGrep(searchRoot, realRoot, pattern, opts) {
   try {
     regex = opts.isRegex ? new RegExp(pattern, opts.caseSensitive ? "" : "i") : new RegExp(escapeRegExp(pattern), opts.caseSensitive ? "" : "i");
   } catch (err) {
-    throw new InvalidRegexError(errorMessage2(err));
+    throw new InvalidRegexError(errorMessage3(err));
   }
   const matches = [];
   let truncated = false;
@@ -7646,7 +8044,7 @@ async function nodeGrep(searchRoot, realRoot, pattern, opts) {
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function errorMessage2(err) {
+function errorMessage3(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function mapPathError(err) {
@@ -7659,7 +8057,7 @@ function mapPathError(err) {
   if (err.code === "ENOENT") {
     return structuredError("not_found", "Path does not exist");
   }
-  return structuredError("resolve_failed", errorMessage2(err));
+  return structuredError("resolve_failed", errorMessage3(err));
 }
 function mapPackError(err) {
   if (err instanceof PackCacheMissError) {
@@ -7674,7 +8072,7 @@ function mapPackError(err) {
   if (err instanceof AbsolutePathError || err instanceof PathOutsideRootError) {
     return mapPathError(err);
   }
-  return structuredError("pack_failed", errorMessage2(err));
+  return structuredError("pack_failed", errorMessage3(err));
 }
 function registerLocalFsTools(server, opts) {
   const packCache = new PackCache();
@@ -7753,7 +8151,7 @@ function registerLocalFsTools(server, opts) {
 `);
       return result;
     } catch (err) {
-      const msg = errorMessage2(err);
+      const msg = errorMessage3(err);
       const elapsedMs = Math.round(performance.now() - started);
       process.stdout.write(`[tool] ${name}  -> threw  ${String(elapsedMs)}ms  ${msg}
 `);
@@ -8114,20 +8512,49 @@ function createReverseMcpPresenceProbe(deps) {
 }
 
 // src/index.ts
+var AUTH_COMMANDS = ["login", "logout", "status"];
+function isAuthCommand(value) {
+  return AUTH_COMMANDS.includes(value);
+}
 function parseArgs(argv) {
   const [first, ...rest] = argv;
-  let command = "serve";
-  let flagArgs = argv;
-  if (first === "login" || first === "logout" || first === "serve" || first === "reverse" || first === "help" || first === "version") {
-    command = first;
-    flagArgs = rest;
-  } else if (first === "--help" || first === "-h") {
-    command = "help";
-    flagArgs = rest;
-  } else if (first === "--version" || first === "-v") {
-    command = "version";
-    flagArgs = rest;
+  if (first === "auth") {
+    const [sub, ...subRest] = rest;
+    if (sub === void 0 || sub === "help" || sub === "--help" || sub === "-h") {
+      return { command: "help", flags: /* @__PURE__ */ new Map() };
+    }
+    if (!isAuthCommand(sub)) {
+      throw new ConfigError(
+        `Unknown auth command: ${sub}. Expected one of: ${AUTH_COMMANDS.join(", ")}.`
+      );
+    }
+    return authArgs(sub, subRest);
+  }
+  if (first === "login" || first === "logout") {
+    return authArgs(first, rest);
+  }
+  if (first === "serve" || first === "reverse" || first === "help" || first === "version") {
+    return { command: first, flags: parseFlags(rest) };
+  }
+  if (first === "--help" || first === "-h") {
+    return { command: "help", flags: parseFlags(rest) };
+  }
+  if (first === "--version" || first === "-v") {
+    return { command: "version", flags: parseFlags(rest) };
+  }
+  return { command: "serve", flags: parseFlags(argv) };
+}
+function authArgs(authCommand, args) {
+  if (args.includes("-h")) {
+    return { command: "help", flags: /* @__PURE__ */ new Map() };
+  }
+  const flags = parseFlags(args);
+  if (flags.has("help")) {
+    return { command: "help", flags };
   }
+  return { command: "auth", authCommand, flags };
+}
+function parseFlags(flagArgs) {
   const flags = /* @__PURE__ */ new Map();
   const unknownPositional = [];
   for (let i = 0; i < flagArgs.length; i += 1) {
@@ -8157,7 +8584,7 @@ function parseArgs(argv) {
       `Unknown positional arguments: ${unknownPositional.join(", ")}. Run \`npx @myspec/mcp-server --help\` for usage.`
     );
   }
-  return { command, flags };
+  return flags;
 }
 function flagString(flags, key) {
   const value = flags.get(key);
@@ -8176,16 +8603,21 @@ function printHelp() {
     "Commands:",
     "  (default)               Start MCP server over stdio",
     "  serve                   Start MCP server over stdio",
-    "  login                   Sign in via browser (chooser page on the webapp)",
-    "  login --paste           Same as login, but never auto-opens a browser. Open",
-    "                          the printed URL yourself; if the page cannot reach this",
-    "                          CLI it shows a `<code>.<state>` token to paste back.",
-    "  login --org <slug>      Sign in and pin that organization. Tokens only work",
+    "  auth login              Sign in via browser (chooser page on the webapp)",
+    "  auth login --paste      Same as auth login, but never auto-opens a browser.",
+    "                          Open the printed URL yourself; if the page cannot reach",
+    "                          this CLI it shows a `<code>.<state>` token to paste back.",
+    "  auth login --org <slug> Sign in and pin that organization. Tokens only work",
     "                          when an organization is active; the CLI asks when you",
     "                          belong to several and this flag is not given.",
-    "  logout                  Sign out and clear the session credentials. A",
+    "  auth logout             Sign out and clear the session credentials. A",
     "                          configured apiToken is KEPT, so an unattended",
     "                          install keeps working.",
+    "  auth status             Show whether you are signed in, the account email and",
+    "                          the active organization. Renews an expired access",
+    "                          token first, as any command does. Exits 2 when not",
+    "                          signed in.",
+    "  login, logout           Aliases for `auth login` and `auth logout`.",
     "  reverse --root <dir>    Connect to ai-agent and expose local_fs tools.",
     "                          The agent WebSocket URL is discovered from the webapp",
     "                          (GET /api/v1/config) using your saved credentials;",
@@ -8238,14 +8670,28 @@ function assertOrgFlagHasValue(flags) {
   }
 }
 async function main(argv = process.argv.slice(2)) {
-  const { command, flags } = parseArgs(argv);
-  switch (command) {
+  const parsed = parseArgs(argv);
+  const { flags } = parsed;
+  switch (parsed.command) {
     case "help":
       printHelp();
       return;
     case "version":
       process.stderr.write(readVersion() + "\n");
       return;
+    case "auth":
+      await runAuthCommand(parsed.authCommand, flags);
+      return;
+    case "reverse":
+      await runReverseCommand(flags);
+      return;
+    case "serve":
+      await runServe(flags);
+      return;
+  }
+}
+async function runAuthCommand(authCommand, flags) {
+  switch (authCommand) {
     case "login":
       assertOrgFlagHasValue(flags);
       await runLogin({
@@ -8257,13 +8703,14 @@ async function main(argv = process.argv.slice(2)) {
     case "logout":
       await runLogout();
       return;
-    case "reverse":
-      await runReverseCommand(flags);
-      return;
-    case "serve":
-    default:
-      await runServe(flags);
+    case "status": {
+      assertNoEnvAccessToken();
+      const { store, config, envApiTokenActive } = await buildCredentialsStore({
+        cliUserAuthUrl: flagString(flags, "user-auth-url")
+      });
+      await runAuthStatus({ store, webappUrl: config.webappUrl, envApiTokenActive });
       return;
+    }
   }
 }
 var REVERSE_DISCOVERY_HINT = "Pass --agent-url <url>, set MYSPEC_AI_AGENT_WS_URL, or run `npx @myspec/mcp-server login` and retry.";
@@ -8291,10 +8738,13 @@ async function resolveReverseAgentUrl(sources) {
       );
     }
     if (stored && sources.persist) {
-      await sources.persist(applyDiscoveredUrls(stored, config.webappUrl, discovered)).catch((err) => {
-        const message = err instanceof Error ? err.message : String(err);
-        warn(`myspec-mcp reverse: could not save discovered URLs (${message})`);
-      });
+      const latest = await sources.loadStored().catch(() => null);
+      if (latest) {
+        await sources.persist(applyDiscoveredUrls(latest, config.webappUrl, discovered)).catch((err) => {
+          const message = err instanceof Error ? err.message : String(err);
+          warn(`myspec-mcp reverse: could not save discovered URLs (${message})`);
+        });
+      }
     }
     return { agentUrl: discovered.aiAgentMcpReverseUrl, discoveredVia: endpoint };
   } catch (err) {
@@ -8353,17 +8803,12 @@ async function buildCredentialsStore(opts = {}) {
     // ConfigError exit — and one that never names the file it came from.
     storedUserAuthUrl: stored?.userAuthUrl ?? usableAuthUrl(fromSettings, settingsPath, warn)
   });
+  const envConfig = readEnvApiToken(config.userAuthUrl, env, warn);
   return {
-    store: createEnvApiTokenStore({
-      fileStore,
-      // `warn` rather than the default sink, so the "cannot be sent as a
-      // header" warning lands wherever the caller's other warnings do.
-      envConfig: readEnvApiToken(config.userAuthUrl, env, warn),
-      settingsPath,
-      warn
-    }),
+    store: createEnvApiTokenStore({ fileStore, envConfig, settingsPath, warn }),
     config,
-    usingEnvApiToken
+    usingEnvApiToken,
+    envApiTokenActive: envConfig !== null
   };
 }
 function warnIfStaticTokenShadowsApiToken(inlineToken, env = process.env, warn = (message) => {
@@ -8407,7 +8852,7 @@ async function runReverseCommand(flags) {
     };
     forceRefresh = () => tokenManager.forceRefresh();
     loadStored = () => store.load();
-    persist = (creds) => store.save(creds);
+    persist = (creds) => saveDiscoveredUrls(store, creds);
   }
   const resolved = await resolveReverseAgentUrl({
     flagAgentUrl: flagString(flags, "agent-url"),
@@ -8460,9 +8905,9 @@ function createPlatformUrlResolver(deps) {
         `Could not discover endpoints from ${configEndpoint(deps.webappUrl)} (response is missing platformUrl). Run \`npx @myspec/mcp-server login\` and retry.`
       );
     }
-    const creds = await deps.tokenManager.getCredentials().catch(() => null);
+    const creds = await deps.store.load().catch(() => null);
     if (creds) {
-      await deps.store.save(applyDiscoveredUrls(creds, deps.webappUrl, discovered)).catch((err) => {
+      await saveDiscoveredUrls(deps.store, applyDiscoveredUrls(creds, deps.webappUrl, discovered)).catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         warn(`myspec-mcp: could not save discovered URLs (${message})`);
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "1.1.1-next.156",
+  "version": "1.1.1-next.158",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {